ToolMesh: Instructions file for Claude Code

ToolMesh — Getting Started with Claude Code

ToolMesh is a secure MCP gateway that turns REST APIs into tools using DADL (Declarative API Description Language). This guide helps you set up ToolMesh and connect your first backend — all from this Claude Code session.

Quick Start

# 1. Copy the example config
cp .env.example .env

# 2. Start ToolMesh
docker compose up -d

# 3. Verify it's running
curl http://localhost:8123/health

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

Connect Your AI Agent

Claude Code

claude mcp add -t http \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -s user toolmesh http://localhost:8123/mcp

Set YOUR_API_KEY to the value of TOOLMESH_API_KEY from your .env file.

Claude Desktop

Add to claude_desktop_config.json:

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

Note: Claude Desktop requires HTTPS. For local development without TLS, edit the JSON file directly (the GUI enforces https://). Use Caddy, Cloudflare Tunnel, or nginx as a reverse proxy for production.

Authentication

Edit .env to set at least one auth method:

# Option A: API key (for Claude Code, scripts)
TOOLMESH_API_KEY=my-api-key

# Option B: Password (for Claude Desktop, browser-based clients)
TOOLMESH_AUTH_PASSWORD=my-password

Without either, all requests are rejected.

Authorization

On by default, nothing to set up: the API key or password above may call every tool. To give other users, roles or plans access to selected backends or tools, copy config/authz.yaml.example to config/authz.yaml. ToolMesh applies changes to it within seconds. See docs/configuration.md.

Add a Backend

ToolMesh supports three backend types: REST via DADL, MCP over HTTP, and MCP over STDIO.

1. Get a DADL file

Browse pre-built DADLs at dadl.ai/browse — or ask Claude Code: