arcade-mcp/libs/arcade-mcp-server/docs/getting-started/quickstart.md

Quick Start

The arcade_mcp_server package provides powerful ways to run MCP servers with your Arcade tools. We recommend using arcade new from the arcade-mcp CLI to create your server project with all necessary files and dependencies.

Recommended: Create with arcade new

1. Install the CLI

uv pip install arcade-mcp

The arcade-mcp package includes the CLI tools and the arcade-mcp-server library.

2. Create Your Server

arcade new my_server
cd my_server

This generates a complete project with:

• server.py - Main server file with MCPApp and example tools

• pyproject.toml - Dependencies and project configuration

• .env.example - Example .env file containing a secret required by one of the generated tools in server.py

The generated server.py includes proper structure with command-line argument handling:

#!/usr/bin/env python3
import sys
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 someone by name."""
    return f"Hello, {name}!"

if __name__ == "__main__":
    transport = sys.argv[1] if len(sys.argv) > 1 else "http"
    app.run(transport=transport, host="127.0.0.1", port=8000)

3. Run Your Server

# Run with uv (recommended)
uv run server.py

# Run with HTTP transport (default)
uv run server.py http

# Run with stdio transport (for Claude Desktop)
uv run server.py stdio

You should see output like:

INFO | Starting server v1.0.0 (my_server)
INFO | Added tool: greet
INFO | Added tool: add_numbers
INFO | Starting MCP server on http://127.0.0.1:8000

For HTTP transport, view your server's API docs at http://127.0.0.1:8000/docs.

4. Configure MCP Clients

Connect your server to AI assistants:

# Configure Claude Desktop
arcade configure claude --from-local

# Configure Cursor IDE
arcade configure cursor --from-local

# Configure VS Code
arcade configure vscode --from-local

That's it! Your MCP server is running and connected to your AI assistant.

Building MCP Servers

The simplest way to create an MCP server programmatically is using MCPApp, which provides a FastAPI-like interface:

from arcade_mcp_server import MCPApp
from typing import Annotated

app = MCPApp(
    name="my_serve_",
    version="1.0.0",
    instructions="Custom MCP server with specialized tools"
)

@app.tool
def calculate(
    expression: Annotated[str, "Mathematical expression to evaluate"]
) -> Annotated[float, "The result of the calculation"]:
    """Safely evaluate a mathematical expression."""
    # Safe evaluation logic here
    return eval(expression, {"__builtins__": {}}, {})

@app.tool
def fetch_data(
    url: Annotated[str, "URL to fetch data from"]
) -> Annotated[dict, "The fetched data"]:
    """Fetch data from an API endpoint."""
    import requests
    return requests.get(url).json()

# Run the server
if __name__ == "__main__":
    app.run(host="0.0.0.0", port=8080, reload=True)

Secrets

Define your tool secrets in an environment file .env in the same directory as your MCPApp, or export as environment variables

# Tool secrets (available to tools via context)
MY_API_KEY="secret-value"
DATABASE_URL="postgresql://..."

Development Tips

Hot Reload

Use the reload=True parameter for development to automatically restart on code changes:

app.run(host="127.0.0.1", port=8000, reload=True)

Logging

• Set log_level="DEBUG" in MCPApp for verbose logging
• In stdio mode, logs go to stderr
• In HTTP mode, logs go to stdout

Docs for your MCP Server

With HTTP transport, access API documentation at:

• http://localhost:8000/docs (Swagger UI)

• http://localhost:8000/redoc (ReDoc)

Next Steps

• Check out the Examples for detailed tutorials
• Learn about Client Integration with Claude Desktop, Cursor, and VS Code
• Explore the MCPApp API for advanced server customization
• Read about Transport Modes (stdio vs HTTP)