Creating a MCP Server

Generate a MCP Server template

Run the following command to start creating your MCP Server:

uv tool run --from arcade-ai arcade new arithmetic

Enter the optional information when prompted:

• Description: Provide a brief explanation of what your MCP Server will do
• Author GitHub username and email: Your contact information
• Generate test and evaluation directories: Whether you want additional directories created for you

After completion, a directory with your MCP Server name (arithmetic) will be created with the following structure:

arithmetic/
├── arcade_arithmetic/       # Core package directory
│   ├── __init__.py
│   └── tools/               # Directory for your tools
│       ├── __init__.py
│       └── hello.py         # Example tool
├── evals/                   # Evaluation directory
│   └── eval_arithmetic.py   # Example evaluation file
├── tests/                   # Test directory
│   ├── __init__.py
│   └── test_arithmetic.py   # Example test file
├── pyproject.toml           # uv project configuration
├── README.md
└── Makefile                 # uv helper commands

Navigate to your MCP Server directory:

cd arithmetic

Set up the development environment

An active virtual environment for your shell(s) is required to run the local development commands.

uv venv --seed -p 3.13

Install dependencies and pre-commit hooks:

make install

This installs all dependencies specified in pyproject.toml, pre-commit hooks for code quality, and your MCP Server in development mode.

The Makefile provides several helpful commands:

• build - Build wheel file using uv
• bump-version - Bump the version in the pyproject.toml file by a patch version
• check - Run code quality tools
• clean-build - Clean build artifacts
• coverage - Generate coverage report
• install - Install the uv environment and install all packages with dependencies
• install-local - Install Arcade components (CLI, TDK, etc.) from source in editable mode. Only use this when you are developing against the latest unreleased code from the arcade-ai repo  main branch instead of the published packages
• test - Test the code with pytest

Activate the environment with:

source .venv/bin/activate

or

uv run

Define your tools

Create a Python file for your tools in the arcade_arithmetic/tools directory.

The following example shows a simple math MCP Server with three tools: add, subtract, and multiply:

# arcade_arithmetic/tools/operations.py
from typing import Annotated
 
from arcade_tdk import tool
 
 
@tool
def add(
    a: Annotated[int, "The first number"],
    b: Annotated[int, "The second number"]
) -> Annotated[int, "The sum of the two numbers"]:
    """
    Add two numbers together
 
    Examples:
        add(3, 4) -> 7
        add(-1, 5) -> 4
    """
    return a + b
 
@tool
def subtract(
    a: Annotated[int, "The first number"],
    b: Annotated[int, "The second number"]
) -> Annotated[int, "The difference of the two numbers"]:
    """
    Subtract the second number from the first
 
    Examples:
        subtract(10, 4) -> 6
        subtract(5, 7) -> -2
    """
    return a - b
 
@tool
def multiply(
    a: Annotated[int, "The first number"],
    b: Annotated[int, "The second number"]
) -> Annotated[int, "The product of the two numbers"]:
    """
    Multiply two numbers together
 
    Examples:
        multiply(3, 4) -> 12
        multiply(-2, 5) -> -10
    """
    return a * b

Update the package initialization files to expose your tools:

# arcade_arithmetic/tools/__init__.py
from arcade_arithmetic.tools.operations import add, multiply, subtract
 
__all__ = ["add", "multiply", "subtract"]

# arcade_arithmetic/__init__.py
from arcade_arithmetic.tools import add, multiply, subtract
 
__all__ = ["add", "multiply", "subtract"]

Test your MCP Server

Write tests for your tools in the tests directory:

# tests/test_operations.py
import pytest
 
from arcade_arithmetic.tools.operations import add, multiply, subtract
 
 
def test_add():
    assert add(3, 4) == 7
    assert add(-1, 5) == 4
    assert add(0, 0) == 0
 
def test_subtract():
    assert subtract(10, 4) == 6
    assert subtract(5, 7) == -2
    assert subtract(0, 0) == 0
 
def test_multiply():
    assert multiply(3, 4) == 12
    assert multiply(-2, 5) == -10
    assert multiply(0, 5) == 0

Run the tests:

make test

Check code quality:

make check

Generate a coverage report (optional):

make coverage

Verify local installation

Your MCP Server should already be installed locally from the make install command. Verify it’s properly registered:

arcade show --local

You should see your MCP Server listed in the output.

Test your tools locally

Serve your MCP Server locally with the Arcade CLI:

arcade serve

You can use the --reload flag to automatically reload the server when you make changes to your MCP Server:

arcade serve --reload

Visit http://localhost:8002/worker/health  to see that your worker is running.

Connect your MCP Server to the Arcade Engine

In another terminal, use a service like ngrok , tailscale , or cloudflare  to give your local worker a public URL.

ngrok http 8002

tailscale funnel 8002

cloudflared tunnel --url http://localhost:8002

Then in your Arcade dashboard:

1. Navigate to the Workers  page.
2. Click Add Worker.
3. Fill in the form with the following values:
   • ID: my-arithmetic-worker
   • Worker Type: Arcade
   • URL: your public URL from ngrok, tailscale, or cloudflare
   • Secret: dev
   • Timeout and Retry: can be left at default values
4. Click Create.

Now, in the Playground , you can see your tools in action.

Deploy your MCP Server to the Arcade Engine

Alternatively, you can deploy your MCP Server to Arcade’s cloud instead of tunneling to it locally.

Find the worker.toml file in your MCP Server’s root directory (where you ran uv tool run --from arcade-ai arcade new arithmetic):

[[worker]]
 
[worker.config]
id = "demo-worker"  # Choose a unique ID
enabled = true
timeout = 30
retries = 3
secret = "<your-secret>"  # This is randomly generated for you by `uv tool run --from arcade-ai arcade new arithmetic`
[worker.local_source]
packages = ["./arithmetic"]  # Path to your MCP Server directory

See Configuring Arcade Deploy for more configuration options.

From the root of your MCP Server, deploy your MCP Server to Arcade’s cloud with:

This may take a while your first time.

arcade deploy

Verify the deployment:

arcade worker list

Package and publish to PyPI

Clean any previous build artifacts:

make clean-build

If you’re updating an existing package, bump the version:

make bump-version

Create a comprehensive README.md file that explains your MCP Server’s purpose, installation, and usage.

Build your package:

make build

Publish to PyPI:

uv publish --token YOUR_PYPI_TOKEN_HERE