Skip to content
ToolMesh

Getting Started

ToolMesh runs as a single Go binary or Docker container. It exposes an MCP server that AI agents connect to.

Prerequisites

Section titled “Prerequisites”
  • Docker and Docker Compose
  • An AI agent that speaks MCP (Claude Desktop, Claude Code, Claude.ai, or any MCP client)
  • Optional: a reverse proxy for TLS (Caddy, Cloudflare Tunnel, nginx)

Quick Start

Section titled “Quick Start”
Terminal window
# Clone the repository
git clone https://github.com/DunkelCloud/ToolMesh.git
cd ToolMesh


# Create your configuration
cp .env.example .env

Open .env and set at least one authentication method:

Terminal window
# For interactive login (Claude Desktop, Claude.ai):
TOOLMESH_AUTH_PASSWORD=my-secure-password


# For programmatic access (Claude Code, scripts):
TOOLMESH_API_KEY=my-api-key

Without a password or API key, all requests are rejected.

Terminal window
# Start ToolMesh
docker compose up -d


# Verify it's running (default port: 8123)
curl http://localhost:8123/health

The MCP endpoint is available at http://localhost:8123/mcp.

TLS (Important)

Section titled “TLS (Important)”

ToolMesh serves plain HTTP. Most MCP clients — including Claude Desktop — require HTTPS and will reject http:// URLs. You need a TLS-terminating reverse proxy in front of ToolMesh:

OptionWhen to use
CaddySelf-hosted with a public domain — automatic Let’s Encrypt certs
Cloudflare TunnelNo open ports needed, zero-config TLS
nginx / TraefikAlready in your stack

For local development only, you can bypass TLS by editing claude_desktop_config.json by hand (the GUI enforces https://).

Connect an AI Agent

Section titled “Connect an AI Agent”

Claude Desktop

Section titled “Claude Desktop”

Add to your Claude Desktop MCP config (claude_desktop_config.json):

{
  "mcpServers": {
    "toolmesh": {
      "url": "https://toolmesh.example.com/mcp"
    }
  }
}

For local development without TLS proxy:

{
  "mcpServers": {
    "toolmesh": {
      "url": "http://localhost:8123/mcp"
    }
  }
}

Claude.ai (Custom Connector)

Section titled “Claude.ai (Custom Connector)”

ToolMesh supports OAuth 2.1 with PKCE S256 for remote access. Configure users in config/users.yaml and use the public HTTPS URL as the MCP endpoint.

Claude Code

Section titled “Claude Code”

Claude Code connects via API key. Set TOOLMESH_API_KEY in your .env, then add the MCP endpoint:

Terminal window
claude mcp add toolmesh http://localhost:8123/mcp

Add a Backend

Section titled “Add a Backend”

Backends are configured in config/backends.yaml.

MCP Backend (proxy an existing MCP server)

Section titled “MCP Backend (proxy an existing MCP server)”
backends:
  - name: memorizer
    transport: http
    url: "https://memorizer.example.com/mcp"
    api_key_env: "MEMORIZER_API_KEY"

Set the credential as an environment variable in .env:

Terminal window
CREDENTIAL_MEMORIZER_API_KEY=sk-mem-xxxxx

Credentials are injected at runtime — the LLM never sees API keys.

REST Backend (via DADL)

Section titled “REST Backend (via DADL)”

Instead of building an MCP wrapper server, describe the REST API declaratively in a .dadl file:

backends:
  - name: github
    transport: rest
    dadl: /app/dadl/github.dadl
    url: "https://api.github.com"

Download DADL files from the DADL Registry or generate one with your LLM:

“Create a DADL for the GitHub API — list repos, open issues, and create pull requests.”

What’s Next

Section titled “What’s Next”