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

Most developers hit the same wall on day two of agent building: the model can reason, but it can’t safely act on behalf of real users. arcade-mcp exists to fix that. With it, you can spin up a Python MCP server, plug in OAuth, and let agents call your tool with user-specific permissions—without ever leaking tokens into the LLM.

Quick Answer: To get started, install arcade-mcp, scaffold a new Python MCP server with arcade new, implement your tool logic, wire in OAuth using Arcade’s auth helpers, and then expose it through the Arcade MCP Gateway so agents (Cursor, Claude, LangGraph, etc.) can call it securely.

---

Frequently Asked Questions

How do I quickly start a new MCP tool with arcade-mcp in Python?

Short Answer: Install the arcade-mcp CLI, run arcade new my_server, then implement your Python tool functions and run uv run server.py to start your MCP server.

Expanded Explanation:
arcade-mcp is the open-source framework Arcade uses internally to build agent-optimized tools. It gives you a minimal, opinionated Python skeleton so you can focus on the tool contract and OAuth, not on protocol plumbing.

The flow looks like this: use the CLI to scaffold a server, define one or more tools (each with a clear schema and behavior), then run the server locally. From there, you can connect it to an MCP-compatible client (like Cursor or Claude Desktop) or front it with Arcade’s MCP Gateway for production use.

Key Takeaways:

• uv tool pip install arcade-mcp gives you the CLI and runtime locally.
• arcade new my_server scaffolds a ready-to-run MCP server in Python with no YAML to wrangle.

---

What’s the step-by-step process to build and run my first custom MCP tool?

Short Answer: Scaffold the server, define your tool, run it locally, then integrate it with your MCP client or Arcade’s MCP Gateway.

Expanded Explanation:
The process is intentionally minimal-ceremony. You start by installing the CLI, then generate a project with one command. Inside that project, you’ll get a Python entrypoint (commonly server.py) and a place to define tools. You implement your tool logic like any other Python function: accept structured inputs, talk to your APIs, return a structured result.

Once your tool is defined, you run the server locally and point your MCP client at it. When you’re ready to go beyond “it works on my machine,” you’ll register the server behind Arcade’s MCP Gateway so real users and production agents can access it with proper auth, audit trails, and permissions.

Steps:

1. Install the CLI

   uv tool pip install arcade-mcp
   

2. Create a new MCP server project

   arcade new my_server
   cd my_server
   

3. Run the server

   Most templates give you a server.py entrypoint:

   uv run server.py
   

   Now your MCP server is running locally and ready to define tools.

---

What’s the difference between using arcade-mcp and just writing a Python API wrapper for my agent?

Short Answer: arcade-mcp gives you an MCP-native runtime and tool framework with OAuth and evals built in, while a simple API wrapper is just ad hoc HTTP code with no authorization model, no schema discipline, and no multi-user story.

Expanded Explanation:
API wrappers are fine for quick demos, but they fall apart fast in production. You end up hardcoding tokens, mixing business logic with auth flows, and leaving the model to guess how to call your functions from loosely defined prompts.

arcade-mcp pushes you toward “agent-optimized tools” instead of arbitrary functions. Tools are explicit (name, input schema, output schema), exposed via the MCP protocol, and designed to be called by agents predictably and cheaply. You get built-in patterns for OAuth, evaluation, and secure execution across multiple users, not a tangle of requests calls and environment variables.

Comparison Snapshot:

• Option A: Ad hoc API wrappers
  • Hand-rolled HTTP calls.
  • Tokens in env vars or, worse, prompts.
  • No shared protocol; every client integration is bespoke.
• Option B: arcade-mcp + MCP runtime
  • Standard MCP protocol understood by Cursor, Claude, LangGraph, etc.
  • OAuth flows and evals built into the framework.
  • Clear, schema-first tools that agents can call reliably.
• Best for: Any agent that needs to safely act in real systems for multiple users, with a clear separation between auth, tools, and model.

---

How do I add OAuth to my custom MCP tool so it can act as the user?

Short Answer: Use Arcade’s auth helpers (client.auth.start + wait_for_completion) to run OAuth outside the LLM, store tokens in Arcade’s runtime, and have your Python tool call external APIs with those user-specific credentials at execution time.

Expanded Explanation:
The whole point of Arcade is “secure agent authorization.” Agents act with user-specific permissions—not shared service accounts—and they never see the tokens. The OAuth dance happens between the user’s browser, your IdP (or provider like Google), and Arcade’s runtime.

At a high level:

• Your tool or agent flow triggers client.auth.start(user_id, "google") (or another provider) to generate an auth link.
• The user clicks the link, signs in, and approves scopes.
• Arcade stores and refreshes tokens for that user; your MCP tool just asks Arcade for an access token when it runs.
• The model only ever sees high-level tool calls (“Google.SendEmail”), not tokens or refresh logic.

What You Need:

• A user identifier (user_id) you can consistently map to the logged-in human.
• Arcade’s Python SDK (arcadepy) and an OAuth provider configured in your Arcade account (e.g., Google).

Conceptual Example (Python side, using Arcade auth):

from arcadepy import Arcade

client = Arcade()
user_id = "user@example.com"

# Start the authorization process
auth_response = client.auth.start(user_id, "google")

# Show auth_response.url to the user (in UI or CLI output)
print(f"Authorize here: {auth_response.url}")

# Later, wait for the user to complete auth
client.auth.wait_for_completion(user_id, "google")

# When your MCP tool executes, you fetch a token (behind the scenes)
token = client.auth.get_access_token(user_id, "google")
# Use `token` to call Google APIs securely in your tool logic

All of this runs in the runtime between AI and action. The LLM never touches the token; it only decides when to call your tool.

---

How do I move from a local arcade-mcp server to a production-ready MCP tool behind Arcade’s MCP Gateway?

Short Answer: Create an Arcade account, set up an MCP Gateway with a slug, select the tools you want to expose, and point your agent framework at the Gateway URL (e.g., https://api.arcade.dev/mcp/my-agent).

Expanded Explanation:
Local dev is great for getting the tool right. Production is where everything breaks: multi-user auth, refresh tokens, audit logs, and security reviews. The MCP Gateway is Arcade’s managed runtime front door—it lets you safely expose tools from one or more MCP servers, wire in OAuth and IDP, and apply governance (RBAC, audit logs, tenant isolation).

You create a Gateway, pick which MCP tools and servers it should expose, and Arcade gives you a URL you can plug into any MCP-compatible client or agent builder. The same tool logic you tested locally now runs with user-specific permissions, scoped OAuth, and a full audit trail.

What You Need:

• A free Arcade account with access to MCP Gateway.
• A slug and configuration for your production MCP Gateway.

Basic Gateway Setup Flow:

• Sign up for Arcade: https://app.arcade.dev/register.

• Navigate to the MCP Gateway page and click Create MCP Gateway.

• Pick a slug, e.g., my-agent. Your MCP URL becomes:

  https://api.arcade.dev/mcp/my-agent
  

• Select the specific tools from your MCP servers that you want agents to see.

• Configure your agent framework (Cursor, Claude, LangGraph, etc.) to talk to that MCP URL.

From there, your agents can send email, create calendar events, post to Slack, or update Salesforce—using your custom tools—without you rebuilding auth and permissioning for each integration.

---

Quick Recap

arcade-mcp is the fastest way to go from “Python function” to “production MCP tool with OAuth.” You install the CLI, scaffold a server, define clear, schema-first tools, and run locally with uv run server.py. Then you wire in OAuth using Arcade’s auth APIs so tools act with user-specific permissions, not shared bots. Finally, you expose everything through the MCP Gateway, giving your agents a single, secure runtime between AI and action—with zero token exposure to the LLM and the governance your security team expects.

Next Step

Get Started