Install & Compatibility
Where this runs
tested against v3.3.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.9
✕ build_error
✕ build_error
66MB installed
● package 66MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
MCPApp
✓ from arcade_serve import MCPApp
✗ from arcade_serve import MCPApp
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
arcade-mcp --version
Debug
Known issues
breakingThe previous tool development kit (`arcade-tdk`) and the old CLI (`arcade-ai`), which implicitly used `arcade-serve` as a development dependency, have been deprecated.fixMigrate to `arcade-mcp-server` for server development and `arcade-mcp` for the CLI. Update `pyproject.toml` dependencies and all import statements.
affects: < 2.3.0 for arcade-ai, all versions of arcade-tdk
gotchaDirect 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.fixFocus 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`.
affects: All versions
gotchaSecrets (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.fixEnsure environment variables (like `MY_SECRET_KEY`) are set. For `MCPApp` tools, secrets are accessed via the `context.get_secret('KEY')` method. affects: All versions (arcade-mcp-server)
Upgrade
Version history
3.3.0latest on PyPI · released Jun 12, 2026
Audit
Dependencies
pythonrequiredRuntime environment
anyiorequiredAsynchronous I/O support (via arcade-mcp-server)
httpxrequiredHTTP client for API interactions (via arcade-mcp-server)
pydanticrequiredData validation and settings management (via arcade-mcp-server)