Skip to Content
HomeBuild toolsCreate a MCP Server

Creating a MCP Server

This guide walks you through the complete process of creating a custom Server for Arcade - from initial setup to publishing on PyPI. You’ll build a simple arithmetic MCP Server with operations like addition, subtraction, and multiplication. When creating or extending an Arcade MCP Server, we make it easy to develop the tool alongside your agent, providing a pleasant local development experience. As your agent will be loading its available tools from the , you can mix existing tools and your locally developed tool by following this guide. You’ll be running your local with the Arcade CLI and registering it with the Engine so that your can find and use your .

Prerequisites

Before starting, make sure you have:

Generate a MCP Server template

Run the following command to start creating your Server:

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

Enter the optional information when prompted:

  • Description: Provide a brief explanation of what your 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 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 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 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
  • 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, , 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 in the arcade_arithmetic/tools directory.

The following example shows a simple math Server with three : 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 :

# 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 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 Server should already be installed locally from the make install command. Verify it’s properly registered:

arcade show --local

You should see your Server listed in the output.

Test your tools locally

Serve your 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 Server:

arcade serve --reload

Visit http://localhost:8002/worker/health  to see that your 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 a public URL.

ngrok http 8002

Then in your Arcade dashboard:

  1. Navigate to the Workers  page.
  2. Click Add .
  3. Fill in the form with the following values:
    • ID: my-arithmetic-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 in action.

Deploy your MCP Server to the Arcade Engine

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

Find the worker.toml file in your 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 Server, deploy your 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 Server’s purpose, installation, and usage.

Build your package:

make build

Publish to PyPI:

uv publish --token YOUR_PYPI_TOKEN_HERE

Using your published MCP Server

Now that your Server is published, you can use it in any Arcade application:

from arcadepy import Arcade
 
# Initialize the Arcade client
client = Arcade()
 
# Use your Tools
response = client.tools.execute(
    tool_name="Arithmetic.Add",
    input={
        "a": 12,
        "b": 34
    },
)
 
print(response.output.value)

Ongoing MCP Server maintenance

As you continue to develop your Server, use these Makefile commands to maintain it:

  • make check - Run code quality checks before committing changes
  • make test - Run tests to ensure your changes don’t break existing functionality
  • make coverage - Monitor test coverage as you add new features
  • make bump-version - Update the version when releasing new changes
  • make build - Build new distribution packages
  • make clean-build - Clean up build artifacts when needed

Next steps

Last updated on
Get an API keyTool Context