{"id":6994,"library":"arcade-serve","title":"Arcade Serve (Infrastructure for ArcadeAI MCP Servers)","description":"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.","status":"maintenance","version":"3.2.3","language":"en","source_language":"en","source_url":"https://github.com/ArcadeAI/arcade-mcp","tags":["AI","agents","server","microservices","API","MCP","toolkit","middleware"],"install":[{"cmd":"pip install arcade-serve","lang":"bash","label":"Install arcade-serve (as infrastructure component)"},{"cmd":"pip install arcade-mcp-server arcade-mcp","lang":"bash","label":"Recommended: Install MCP Server framework and CLI"}],"dependencies":[{"reason":"Runtime environment","package":"python","optional":false},{"reason":"Asynchronous I/O support (via arcade-mcp-server)","package":"anyio","optional":false},{"reason":"HTTP client for API interactions (via arcade-mcp-server)","package":"httpx","optional":false},{"reason":"Data validation and settings management (via arcade-mcp-server)","package":"pydantic","optional":false}],"imports":[{"note":"`arcade-serve` provides underlying infrastructure; direct user imports are rare. Most development is done using `arcade-mcp-server`.","wrong":"from arcade_serve import ...","symbol":"MCPApp, Context","correct":"from arcade_mcp_server import MCPApp, Context"}],"quickstart":{"code":"# Install the Arcade CLI and create a new MCP server project\npip install arcade-mcp uv\nuv tool install arcade-mcp\narcade new my_server\n\n# Navigate to the project directory\ncd my_server/src/my_server\n\n# server.py (example file created by 'arcade new')\nfrom typing import Annotated\nfrom arcade_mcp_server import MCPApp\n\napp = MCPApp(name=\"my-tools\", version=\"1.0.0\")\n\n@app.tool\ndef greet(name: Annotated[str, \"Name to greet\"]) -> str:\n    \"\"\"Greet someone by name.\"\"\"\n    return f\"Hello, {name}!\"\n\n@app.tool(requires_secrets=[\"MY_SECRET_KEY\"])\ndef whisper_secret(context: Context) -> Annotated[str, \"The last 4 characters of the secret\"]:\n    \"\"\"Reveal the last 4 characters of a secret\"\"\"\n    # Secrets are injected into the context at runtime\n    try:\n        secret = context.get_secret(\"MY_SECRET_KEY\")\n    except Exception as e:\n        return str(e)\n    return \"The last 4 characters of the secret are: \" + secret[-4:]\n\nif __name__ == \"__main__\":\n    # To run the server for development with hot reload\n    app.run(reload=True)\n    # For Claude Desktop, run with stdio transport\n    # python -m arcade_mcp_server stdio\n    # For HTTP clients, run with http transport\n    # python -m arcade_mcp_server --host 0.0.0.0 --port 8080","lang":"python","description":"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."},"warnings":[{"fix":"Migrate to `arcade-mcp-server` for server development and `arcade-mcp` for the CLI. Update `pyproject.toml` dependencies and all import statements.","message":"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.","severity":"breaking","affected_versions":"< 2.3.0 for arcade-ai, all versions of arcade-tdk"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure environment variables (like `MY_SECRET_KEY`) are set. For `MCPApp` tools, secrets are accessed via the `context.get_secret('KEY')` method.","message":"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.","severity":"gotcha","affected_versions":"All versions (arcade-mcp-server)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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 ...`.","cause":"Attempting to import from the deprecated `arcade-tdk` package after migration or in a new `arcade-mcp-server` project.","error":"ModuleNotFoundError: No module named 'arcade_tdk'"},{"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.","cause":"Trying to use the old `arcade-ai` CLI command `arcade serve` after migrating or with a new `arcade-mcp` installation.","error":"Command 'arcade serve' not found"},{"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.","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.","error":"ToolRuntimeError: Error during tool execution. Additional context needed before retry."}]}