ToolMesh CLAUDE.md

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.

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:

"Create a DADL for the Hetzner Cloud API — list servers, create server, delete server"

Place the .dadl file in the dadl/ directory.

2. Register the backend

Copy the example config and add your backend:

cp config/backends.yaml.example config/backends.yaml

Add an entry to config/backends.yaml:

backends:
  - name: deepl
    transport: rest
    dadl: deepl.dadl
    url: "https://api.deepl.com/v2"