Skip to content

Get ToolMesh running with Docker Compose

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

  • 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)
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.

Authorization is on, with nothing to set up. The password or API key above may call every tool. Any other caller gets nothing until a grant names it. To give other users, roles or plans access to selected backends or tools, see Authorization.

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.

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

If the proxy runs in another container or on another machine, set TOOLMESH_TRUSTED_PROXIES to its own address (for a container a fixed one, not the Compose network), so that ToolMesh counts its login limits per client and not per proxy; a proxy on the same host needs nothing. See Client address.

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

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"
}
}
}

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. With users.yaml in place, plan pro and role admin may call every tool and plan free every read tool; grant other plans or roles their tools in config/authz.yaml.

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

Terminal window
claude mcp add -t http -H "Authorization: Bearer MY_API_KEY" -s user toolmesh http://localhost:8123/mcp

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.

To keep credentials out of .env and out of the container environment, set CREDENTIAL_STORE=command: ToolMesh then takes them, and TOOLMESH_AUTH_PASSWORD or TOOLMESH_API_KEY as well, from a command such as a sops decryption or vault kv get, and keeps them in memory only. With ergosum, the key that opens them is released only on the machine it is bound to. See Credential stores.

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"

The entry’s name decides which credentials the backend may read, CREDENTIAL_GITHUB_* here. If a DADL needs credentials or hosts beyond that, ToolMesh refuses the backend at load and logs the line to add; see Credential and host binding.

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.”