Handl MCP Server

This project exposes the Handl API as MCP tools using Python and FastMCP.

How The Project Is Organized

• server.py Starts the MCP server.
• handl_mcp/server.py Creates the shared FastMCP app object.
• handl_mcp/client.py Handles HTTP requests to the Handl API.
• handl_mcp/tools/ One file per MCP tool.
• handl_mcp/formatters.py Turns API responses into readable text.
• handl_mcp/models.py Shared input types used by multiple tools.

How A Tool Works

Most tool files follow the same pattern:

1. Import the shared mcp object.
2. Add @mcp.tool(...) above a function.
3. Accept normal Python arguments.
4. Call the Handl API through get_client().
5. Return a string.

Example:

@mcp.tool(name="handl_get_ticket")
def handl_get_ticket(id: str) -> str:
    data = get_client().get(f"/api/tickets/{id}")
    return format_ticket_details(data["ticket"])

Run It

Install dependencies:

pip install -e .

Run the server locally:

python server.py

The server will listen on:

http://localhost:8000/mcp

Docker

Build the image:

docker build -t handl-mcp .

Run the container:

docker run --rm -p 8000:8000 \
  -e HANDL_API_BASE_URL=https://handl.veridox.nl \
  -e HANDL_API_TOKEN=your_token_here \
  handl-mcp

The container serves Streamable HTTP on:

http://localhost:8000/mcp

Or run it with Docker Compose:

docker compose up --build

Reverse Proxy

Put HTTPS and your public hostname on the proxy in front of the container. Forward requests to the container on port 8000 and keep the /mcp path intact.

Because the server runs with stateless_http=True, it is a better fit for running behind a proxy or load balancer.

GitHub Container Registry

This repo includes a GitHub Actions workflow at .github/workflows/docker-image.yml. When you push to main, it builds the Docker image and pushes it to:

ghcr.io/<owner>/<repo>

Example pull command:

docker pull ghcr.io/your-org/handl-mcp:latest

Deploy To A Docker Host From GitHub

On your Docker host, create a stack folder:

mkdir -p /opt/stacks/handl-mcp
cd /opt/stacks/handl-mcp

Copy compose.stack.yml into that folder, rename it to docker-compose.yml, and update:

image: ghcr.io/YOUR_GITHUB_OWNER/YOUR_REPO_NAME:latest
HANDL_API_BASE_URL: https://handl.veridox.nl
HANDL_API_TOKEN: your_token_here

Then start the stack:

docker compose pull
docker compose up -d

For future updates:

docker compose pull
docker compose up -d

Good Files To Read First

• server.py
• handl_mcp/server.py
• handl_mcp/client.py
• handl_mcp/tools/get_ticket.py
• handl_mcp/tools/create_ticket.py