arcade-mcp: Python Framework for Building MCP Servers with Built-In OAuth

What arcade-mcp is and what problem it solves

Building MCP tools that call third-party APIs requires handling OAuth flows, storing tokens securely, refreshing them before expiry, and scoping them correctly per call. Most teams end up writing this plumbing themselves or asking users to paste tokens into config files. arcade-mcp solves it with a single decorator.

A tool that reads a user's GitHub repositories declares its requirement in one line:

from arcade_mcp_server import MCPApp, Context
from arcade_mcp_server.auth import GitHub

app = MCPApp(name="gh", version="1.0.0")

@app.tool(requires_auth=GitHub(scopes=["repo"]))
async def list_my_repos(context: Context) -> list[str]:
    """List the authenticated user's GitHub repositories."""
    token = context.get_auth_token_or_empty()
    ...

When this tool is invoked through Arcade Cloud, the user is presented with a URL to complete the OAuth challenge in their browser. On success, the token is injected into the context object for that call. Subsequent calls reuse and refresh the token automatically. The client application and the LLM never receive the token value.

This is the core pitch of the framework: the authorization contract is in the code, not in documentation, and the secrets never leave Arcade's infrastructure during an authorized call.

Installing arcade-mcp and scaffolding a new server

The CLI is distributed as a uv tool:

uv tool install arcade-mcp

Scaffolding a new server creates a pyproject.toml, a .env.example, and a server.py with example tools:

arcade new my_server
cd my_server/src/my_server

A minimal tool definition requires only the MCPApp and a decorated function:

from typing import Annotated
from arcade_mcp_server import MCPApp

app = MCPApp(name="my_server", version="1.0.0")

@app.tool
def greet(name: Annotated[str, "Name to greet"]) -> str:
    """Greet a person by name."""
    return f"Hello, {name}!"

if __name__ == "__main__":
    app.run(transport="stdio")

Running the server in stdio mode (for Claude Desktop and CLI tools) or HTTP+SSE mode (for Cursor and VS Code):

uv run server.py
uv run server.py http

Configure MCP clients with the arcade configure command:

arcade configure claude
arcade configure cursor --transport http --port 8080
arcade configure vscode --entrypoint my_server.py

OAuth provider helpers and what they cover

The framework ships 23 helper classes for popular OAuth providers: Asana, Atlassian, Attio, Calendly, ClickUp, Discord, Dropbox, Figma, GitHub, Google, Hubspot, Linear, LinkedIn, Microsoft, MicrosoftPowerBI, Notion, PagerDuty, Reddit, Slack, Spotify, Twitch, X, and Zoom. Each class encapsulates the provider's token endpoint, scope model, and refresh behavior.

For any OAuth API not in that list, the generic OAuth2 class accepts a custom provider configuration, and the Arcade Dashboard is where you register the OAuth app credentials.

For API keys and other secrets rather than OAuth tokens, the framework also handles secure injection at runtime. The secret is stored in Arcade's encrypted environment and injected into the tool call context, following the same model as OAuth tokens.

This list covers most of the integrations that enterprise teams build on top of AI agents today. The notable absences are Salesforce and AWS, which are not listed in the README's helper class table.

Full MCP spec coverage and the eval tooling

Beyond tools and authentication, arcade-mcp covers the full Model Context Protocol specification: tools, resources, prompts, sampling, elicitation, progress reporting, and logging. The decorator API applies uniformly across these primitives.

The framework includes arcade evals for testing tool-call accuracy against real LLMs. The examples/evals/ directory contains patterns for running evaluation suites. This matters because MCP tools are functions called by a model, and verifying that the model actually calls the right tool with the right arguments for a given user query requires a different test strategy than unit testing the tool function itself.

To install from source rather than via uv tool:

git clone https://github.com/ArcadeAI/arcade-mcp.git
cd arcade-mcp
make install

This requires Python 3.10 or higher and uv. The Makefile install target runs uv sync with the all and dev extras and sets up pre-commit hooks.

The pyproject.toml pins mcp>=1.9.0,<2.0.0 with a comment explaining that the 2.0 mcp package changed the streamable-http client API in a way that breaks the evals loaders. This pin applies to the arcade-mcp package's evals extra; standalone tool servers do not need the mcp package at all unless they use MCP client features.

Arcade Cloud deployment versus standalone operation

Running arcade deploy after arcade login packages the server, discovers required secrets, and deploys to Arcade Cloud. Once deployed, the Arcade Engine fulfills the authorized tool calling flows for end users: it presents the OAuth consent URL, stores the token, and injects it on each call.

Standalone operation is documented as an alternative. In standalone mode, the server runs in any MCP client over stdio or HTTP. In this case, the caller supplies access tokens for tools that declare requires_auth, and HTTP endpoints in production must be protected with Resource Server Auth (OAuth 2.1 Bearer tokens validated against your identity provider).

The practical difference is that Arcade Cloud manages the end-user OAuth consent experience and token lifecycle. Without it, your application must handle those flows, which returns the problem that arcade-mcp set out to solve. Teams who need fully self-hosted authorization, or whose security policy prohibits external token storage, will need to implement the consent flow themselves.

The project's current version is 1.16.1, and it powers the prebuilt tools at Arcade.dev. The last push to the repository was on 2026-09-25. The license is MIT. The pyproject.toml shows that the framework requires Python 3.10, 3.11, 3.12, or 3.13. The development install adds openai, anthropic, mcp, scipy, numpy, and scikit-learn as optional evals dependencies, which means the eval tooling is usable with both Anthropic and OpenAI models without changing the core server code.

What arcade-mcp does not provide

arcade-mcp is a server-side framework. It does not include a client library for consuming MCP tools from application code, though the examples/mcp_servers/authorization/ directory shows patterns for resource server authentication on the server side.

The framework does not manage MCP server discovery or routing across multiple servers. If your use case involves dozens of servers whose capabilities need to be aggregated, that orchestration layer is outside the scope of arcade-mcp. Each server is a self-contained Python process; combining them requires an MCP host or router that arcade-mcp does not supply.

The documentation at docs.arcade.dev is the primary reference; the README covers setup and the key features but defers longer examples to the docs site and to examples/mcp_servers/. Anyone evaluating the framework for complex scenarios such as tool chaining, end-to-end agents, or custom eval suites should look at those directories rather than relying on the README alone. The examples/evals/ directory contains patterns for running evaluation suites against real LLM endpoints.

A closely related alternative is the official MCP Python SDK from Anthropic, which covers the protocol implementation but does not include the OAuth provider helpers or the Arcade Cloud deployment path. The difference in approach is that arcade-mcp treats authorization as a first-class concern built into the tool definition, while the base SDK leaves OAuth handling to the implementer. For teams that need only the protocol and no hosted OAuth infrastructure, the base SDK is lighter. For teams building tools that call OAuth-gated APIs on behalf of end users, arcade-mcp removes the most repetitive part of the implementation.

Editorial conclusion

arcade-mcp is the right framework when you need MCP tools that require OAuth or API key secrets and want those secrets managed outside your tool code. It is the wrong choice when you need a fully self-hosted authorization stack without any dependency on Arcade Cloud: the authorized tool calling feature for end users depends on Arcade Cloud fulfilling the OAuth challenge. Standalone deployment is documented, but you supply your own tokens in that case, which shifts the token management burden back to the caller. Before building on arcade-mcp, verify that your target MCP clients (Claude Desktop, Cursor, VS Code) are compatible with the transport you plan to use, and check that the mcp package version pin at less than 2.0.0 does not conflict with other dependencies in your project.

Frequently asked questions

Official sources

1. ArcadeAI/arcade-mcp on GitHub
2. Issues
3. License: MIT
4. Project website
5. README