Arcade MCP Server Framework

1.19.3 · active · verified Wed Apr 15

Arcade MCP (Model Context Protocol) Server is a secure framework for building and running AI-powered tools and agents. It enables AI assistants and development tools to interact with your custom tools through a standardized protocol, supporting seamless integration across different AI platforms. The current version is 1.19.3, and it receives frequent updates and feature releases.

Common errors

```
ModuleNotFoundError: No module named 'arcade_mcp_server'
```
cause The 'arcade_mcp_server' package is not installed in the Python environment.

fix Install the package using pip: 'pip install arcade-mcp-server'.
```
ImportError: cannot import name 'MCPApp' from 'arcade_mcp_server'
```
cause The 'MCPApp' class is not available in the 'arcade_mcp_server' module, possibly due to an outdated version.

fix Ensure you have the latest version installed: 'pip install --upgrade arcade-mcp-server'.
```
ValueError: Invalid tool definition in 'tools/math_tools.py'
```
cause The tool function in 'math_tools.py' lacks proper annotations or the '@app.tool' decorator.

fix Add the '@app.tool' decorator and ensure all parameters and return types are properly annotated.
```
RuntimeError: Server failed to start due to missing 'ARCADE_WORKER_SECRET' environment variable.
```
cause The 'ARCADE_WORKER_SECRET' environment variable is not set, leading to authentication issues.

fix Set the 'ARCADE_WORKER_SECRET' environment variable with a secure value before starting the server.
```
TypeError: 'NoneType' object is not iterable in 'tools/text_tools.py'
```
cause A function in 'text_tools.py' is returning 'None' instead of an iterable, possibly due to missing return statements.

fix Ensure all functions return the expected iterable types and handle cases where 'None' might be returned.

Warnings

gotcha Local HTTP servers for `arcade-mcp-server` do not currently support tool-level authorization and secrets. For local development requiring these features, use the `stdio` transport. Public HTTP servers should follow deployment guides for secure remote deployment.
Fix: Use `stdio` transport locally for tools requiring authorization/secrets, or deploy to a secure environment for public HTTP access. When running, specify `python server.py stdio` or omit the transport argument for default `stdio`.
gotcha For AI agents to effectively understand and utilize your tools, it is crucial to use `typing.Annotated` for parameter and return type descriptions, and provide clear docstrings for each tool.
Fix: Always include `Annotated` types for tool parameters and return values (e.g., `name: Annotated[str, "Description"]`) and descriptive docstrings for your tool functions.
gotcha The `arcade_mcp_server` package collects anonymous usage data upon server start, including server configuration, metadata, runtime environment details, and error messages.
Fix: Users concerned about data collection should review the privacy policy and consider their deployment environment.

Install

pip install arcade-mcp-server Install core library
uv tool install arcade-mcp Install Arcade CLI for project scaffolding (recommended)

Imports

MCPApp
```
from arcade_mcp_server import MCPApp
```
Context
```
from arcade_mcp_server import Context
```

Quickstart

This quickstart demonstrates how to create a basic MCP server with `MCPApp`, define tools using the `@app.tool` decorator, and handle secrets. The `arcade-mcp` CLI can be used to scaffold a complete project.

from typing import Annotated
from arcade_mcp_server import MCPApp, Context
import os

app = MCPApp(name="my-tools", version="1.0.0", log_level="DEBUG")

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

# Example tool requiring a secret, typically set in .env or as an environment variable
@app.tool(requires_secrets=["MY_SECRET_KEY"])
def whisper_secret(context: Context) -> Annotated[str, "The last 4 characters of the secret"]:
    """Reveal the last 4 characters of a secret"""
    secret_value = context.get_secret("MY_SECRET_KEY")
    if secret_value:
        return f"Your secret ends with: {secret_value[-4:]}"
    return "Secret not found or not configured."

if __name__ == "__main__":
    # Ensure MY_SECRET_KEY is set in your environment for the whisper_secret tool to work
    # For local testing, you might use: export MY_SECRET_KEY="your_development_secret"
    # Or, for more robust handling, use a .env file and a library like python-dotenv
    # os.environ['MY_SECRET_KEY'] = os.environ.get('MY_SECRET_KEY', 'default_secret_for_dev')
    app.run()

view raw JSON →