Arcade Serve (Infrastructure for ArcadeAI MCP Servers)

3.2.3 · maintenance · verified Thu Apr 16

Arcade Serve provides foundational serving infrastructure for ArcadeAI tools and workers, enabling agents to interact with custom functionalities via the Model Context Protocol (MCP). While `arcade-serve` itself is a lower-level component, user-facing development and deployment of MCP servers are now primarily managed through the `arcade-mcp-server` Python package and the `arcade-mcp` command-line interface. The library is currently at version 3.2.3 and is part of an actively developed ecosystem with frequent updates to its primary user-facing components.

Common errors

```
ModuleNotFoundError: No module named 'arcade_tdk'
```
cause Attempting to import from the deprecated `arcade-tdk` package after migration or in a new `arcade-mcp-server` project.

fix Replace all imports from `arcade_tdk` with `arcade_mcp_server`. For example, `from arcade_tdk.auth import ...` becomes `from arcade_mcp_server.auth import ...`.
```
Command 'arcade serve' not found
```
cause Trying to use the old `arcade-ai` CLI command `arcade serve` after migrating or with a new `arcade-mcp` installation.

fix Use `uv run server.py` or `python -m arcade_mcp_server [transport]` to run your server, and `arcade deploy` for deployment with the `arcade-mcp` CLI.
```
ToolRuntimeError: Error during tool execution. Additional context needed before retry.
```
cause An AI agent or client attempted to use a tool, but it required additional context (e.g., user authentication or more information) that was not provided.

fix Review the tool's implementation and the error details. If the tool is designed to request more context, ensure the client/agent is configured to handle `ContextRequiredToolError` and provide the necessary input. For authentication, verify OAuth flows are correctly set up.

Warnings

breaking The previous tool development kit (`arcade-tdk`) and the old CLI (`arcade-ai`), which implicitly used `arcade-serve` as a development dependency, have been deprecated.
Fix: Migrate to `arcade-mcp-server` for server development and `arcade-mcp` for the CLI. Update `pyproject.toml` dependencies and all import statements.
gotcha Direct interaction with the `arcade-serve` package is generally not the intended way to develop custom AI tools. It functions more as an internal infrastructure component.
Fix: Focus on using the `arcade-mcp-server` package for Python-based tool development and the `arcade-mcp` CLI for project scaffolding, running, and deployment. Refer to the official ArcadeAI documentation for `arcade-mcp`.
gotcha Secrets (e.g., API keys) required by tools must be configured correctly, either in a `.env` file for local development or within the Arcade Dashboard for production. Failure to do so will result in runtime errors when tools requiring secrets are invoked.
Fix: Ensure environment variables (like `MY_SECRET_KEY`) are set. For `MCPApp` tools, secrets are accessed via the `context.get_secret('KEY')` method.

Install

pip install arcade-serve Install arcade-serve (as infrastructure component)
pip install arcade-mcp-server arcade-mcp Recommended: Install MCP Server framework and CLI

Imports

MCPApp, Context
wrong:
```
from arcade_serve import ...
```
correct:
```
from arcade_mcp_server import MCPApp, Context
```
`arcade-serve` provides underlying infrastructure; direct user imports are rare. Most development is done using `arcade-mcp-server`.

Quickstart

The fastest way to get started with ArcadeAI servers is by using the `arcade-mcp` CLI tool to scaffold a new project, which sets up `arcade-mcp-server`. This example demonstrates a basic server with two tools, one requiring a secret, and shows how to run it in different modes.

# Install the Arcade CLI and create a new MCP server project
pip install arcade-mcp uv
uv tool install arcade-mcp
arcade new my_server

# Navigate to the project directory
cd my_server/src/my_server

# server.py (example file created by 'arcade new')
from typing import Annotated
from arcade_mcp_server import MCPApp

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

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

@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"""
    # Secrets are injected into the context at runtime
    try:
        secret = context.get_secret("MY_SECRET_KEY")
    except Exception as e:
        return str(e)
    return "The last 4 characters of the secret are: " + secret[-4:]

if __name__ == "__main__":
    # To run the server for development with hot reload
    app.run(reload=True)
    # For Claude Desktop, run with stdio transport
    # python -m arcade_mcp_server stdio
    # For HTTP clients, run with http transport
    # python -m arcade_mcp_server --host 0.0.0.0 --port 8080

view raw JSON →