How do I get started with arcade-mcp to build a custom MCP tool in Python with OAuth?

Most teams hit the same wall with agents: the model can reason, but it can’t safely do anything useful in your real systems. arcade-mcp exists to fix that. In a few minutes, you can spin up a Python MCP server, add OAuth-backed tools, and let agents take real actions with user-specific permissions—without rebuilding auth from scratch.

Quick Answer: Install arcade-mcp, scaffold a new server with arcade new, define your tools in Python, and use Arcade’s built-in OAuth support so your MCP tools can call APIs like Google with user-specific, scoped access and zero token exposure to the LLM.

Frequently Asked Questions

How do I start building a Python MCP tool using arcade-mcp?

Short Answer: Install the arcade-mcp CLI, run arcade new my_server, then implement your MCP tools in the generated Python project and run the server with uv run server.py.

Expanded Explanation:
arcade-mcp gives you the same open-source MCP framework Arcade uses internally. You don’t have to hand-roll the MCP protocol or auth flows; you just define tools in Python functions/classes and let the framework handle the wiring. The generated project includes the basic server scaffold, so you can focus on actual tool behavior (e.g., “send an email”, “create a Jira ticket”) instead of transport and schema boilerplate.

The flow looks like this: install the CLI, create a new project, add one or more tools with clear schemas, then run the server locally and connect it to your MCP-compatible client (Cursor, Claude Desktop, LangGraph, or your own runtime). From there, you iterate—refining schemas, adding OAuth, and eventually deploying behind Arcade’s MCP Gateway.

Key Takeaways:

• Use arcade new to scaffold an MCP server in seconds—no YAML, no protocol plumbing.
• Implement Python tools in the generated project and run them with uv run server.py.

---

What is the step-by-step process to add OAuth to my Python MCP tool?

Short Answer: Use Arcade’s built-in OAuth flow: start auth for a user with client.auth.start(...), wait for completion, then use the stored, rotated credentials inside your MCP tool—without ever exposing tokens to the LLM.

Expanded Explanation:
Most DIY agent stacks fall apart when you add OAuth: refresh tokens expire, service accounts don’t match user permissions, and suddenly you’ve built half of Okta by accident. The arcade-mcp framework is opinionated here: OAuth is a first-class concept, not an afterthought. You start an authorization flow for a specific user and provider (e.g., "google"), let Arcade manage token exchange, refresh, and storage, and then call provider APIs inside your tools with credentials injected at runtime.

At development time, you can run with local evals and bring-your-own-credentials. In production, you wire OAuth to your IDP (or Google Workspace, Microsoft, etc.), and agents act with the actual user’s scopes. The LLM only ever sees tool inputs/outputs—not raw tokens.

Steps:

1. Install and scaffold your server
   • Install CLI:

     uv tool pip install arcade-mcp
     

   • Create a new server:

     arcade new my_server
     cd my_server
     

2. Wire OAuth with Arcade’s SDK
   Inside your backend (or a small auth service), start an auth session:

   from arcadepy import Arcade
   
   client = Arcade()
   user_id = "user@example.com"
   
   auth_response = client.auth.start(user_id, "google")
   # Redirect the user to auth_response.url to complete consent
   

   Then wait for completion (e.g., via webhook or polling) and store the resulting Arcade-side user handle.
3. Use OAuth-backed credentials in your MCP tool
   In your MCP tool implementation, use Arcade’s libraries or environment wiring to call APIs like Gmail/Calendar with the user’s tokens that Arcade maintains behind the scenes. Your tool just sees “I can call Google as this user,” not raw secrets.

---

What’s the difference between using arcade-mcp and just wrapping APIs myself?

Short Answer: arcade-mcp gives you agent-optimized tools, built-in OAuth, and MCP compatibility, whereas DIY API wrappers leave you rebuilding auth, schemas, and governance while agents struggle with brittle, unstructured endpoints.

Expanded Explanation:
You can absolutely call requests against the Google API directly—but agents are terrible at free-form HTTP. They need stable tool schemas, strong parameter typing, and predictable error surfaces. That’s the gap arcade-mcp fills: it turns your actions into MCP-native tools with JSON schemas that models understand, while the runtime handles retries, rate limits, and auth.

On top of that, arcade-mcp is shipped as part of Arcade’s broader MCP runtime: tools plug into a system that already knows how to do OAuth, handle user-specific permissions, and expose tools through MCP Gateway to multiple clients. With ad-hoc wrappers, you still have to solve: “Which user is this? Which scopes? Where are the tokens? Who can see them? How do I audit tool calls?” With arcade-mcp, those are first-class features, not future TODOs.

Comparison Snapshot:

• Option A: DIY API wrappers
  • Manually call APIs, manage OAuth, invent your own schemas.
  • Every tool re-solves auth, error handling, and logging differently.
• Option B: arcade-mcp + Arcade runtime
  • MCP-native tools, shared OAuth, evals, and schemas.
  • Works with Cursor, Claude, LangGraph, and more via MCP.
• Best for: Teams that want production-ready agents with user-specific permissions, clean schemas, and no reimplementation of auth and governance.

---

How do I actually run and connect my arcade-mcp server to an agent or IDE?

Short Answer: Run the generated Python server with uv run server.py, then point your MCP client (e.g., Cursor, Claude Desktop, or Arcade MCP Gateway) at the server URL or socket.

Expanded Explanation:
Once your MCP tools are implemented, you need a runtime that speaks MCP. The generated project gives you a ready-to-run server entrypoint. For local development, you’ll typically run it on a port or socket and configure your client (IDE, agent runner, or Arcade Gateway) to connect. Arcade also ships an MCP Gateway that exposes your MCP servers over HTTPS, so you can connect from cloud-hosted agents without exposing your local dev machine.

As you move towards production, you can deploy the server into your cloud, VPC, or even an air-gapped environment. MCP Gateway handles multi-tenant routing, auth, and audit logs so you can control exactly which tools are available to which agents.

What You Need:

• A Python environment with uv and arcade-mcp installed:

  uv tool pip install arcade-mcp
  

• A running server:

  uv run server.py
  

• An MCP client or runtime (Cursor, Claude, LangGraph, or Arcade MCP Gateway) configured with your server address.

---

How should I design my OAuth-backed MCP tools for long-term success?

Short Answer: Treat each tool as a clear, high-level action (not a generic API proxy), enforce user-specific permissions at the tool boundary, and rely on Arcade’s OAuth runtime so tokens never touch the LLM.

Expanded Explanation:
Your agents are only as good as your tools. A “Swiss Army knife” HTTP tool with 25 optional parameters will confuse the model, cost more tokens, and be harder to secure. Instead, design focused tools with names like Google.SendEmail, Google.CreateEvent, Gmail.ListEmails, each with a tight schema that encodes your authorization and guardrails.

On the auth side, authorization must be enforced in code, not prompts. Use Arcade’s OAuth flows to bind a user identity to each tool invocation, and gate sensitive tools behind explicit scopes and just-in-time consent. When the agent calls Google.SendEmail, your tool should know which user’s identity to act as and what they’re allowed to do—then rely on Arcade’s audit logs and RBAC to keep security teams happy.

Why It Matters:

• Better agent behavior and lower cost: Agent-optimized tools with clear schemas lead to fewer calls, fewer retries, and more predictable outcomes.
• Real production readiness: User-specific permissions, audit trails, and scoped OAuth are the difference between a cool demo and an agent your security team will actually approve.

---

Quick Recap

To get started with arcade-mcp in Python, you install the CLI, scaffold a new MCP server with arcade new, and implement focused, agent-optimized tools. When you’re ready for OAuth, you hook into Arcade’s authorization flow with client.auth.start(...), let the runtime manage tokens and refresh, and call APIs like Google as the actual user—no service accounts, no token exposure to the LLM. Finally, you run your server with uv run server.py and connect it via MCP to your preferred client or to Arcade’s MCP Gateway for production deployments.

Next Step

Get Started