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.
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”# Clone the repositorygit clone https://github.com/DunkelCloud/ToolMesh.gitcd ToolMesh
# Create your configurationcp .env.example .envOpen .env and set at least one authentication method:
# For interactive login (Claude Desktop, Claude.ai):TOOLMESH_AUTH_PASSWORD=my-secure-password
# For programmatic access (Claude Code, scripts):TOOLMESH_API_KEY=my-api-keyWithout 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.
# Start ToolMeshdocker compose up -d
# Verify it's running (default port: 8123)curl http://localhost:8123/healthThe 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:
| Option | When to use |
|---|---|
| Caddy | Self-hosted with a public domain — automatic Let’s Encrypt certs |
| Cloudflare Tunnel | No open ports needed, zero-config TLS |
| nginx / Traefik | Already 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://).
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. 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
Section titled “Claude Code”Claude Code connects via API key. Set TOOLMESH_API_KEY in your .env, then add the MCP endpoint:
claude mcp add -t http -H "Authorization: Bearer MY_API_KEY" -s user toolmesh http://localhost:8123/mcpAdd 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:
CREDENTIAL_MEMORIZER_API_KEY=sk-mem-xxxxxCredentials 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.
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"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.”
What’s Next
Section titled “What’s Next”- Architecture — understand the execution pipeline
- DADL — describe REST APIs without code
- Configuration — all environment variables
- Authentication — OAuth 2.1, API keys, multi-user