ToolMesh — Let AI agents touch real systems. Safely.

The missing control layer between AI agents and enterprise systems. ToolMesh turns uncontrolled AI tool calls into a governed, auditable process — and connects any REST API or MCP server in minutes, not months.

30 lines of YAML. No server to build.

In practice, MCP servers only expose a fraction of the REST API they wrap — and you'll hit the gaps fast. ToolMesh lets you replace the wrapper layer with .dadl files — a declarative YAML format that describes any REST API as MCP tools. No wrapper server to build, deploy, or maintain.

Current:    Claude → ToolMesh → MCP Server → REST API
With DADL:  Claude → ToolMesh → REST API (via .dadl file)

You don't write the YAML by hand. You ask an LLM. Claude, GPT, Gemini — any model that knows the DADL spec generates a working .dadl file in seconds. Describe what you need, drop the file into config/dadl/, done.

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

10 seconds. Works with any LLM that knows the format.

And unlike MCP gateways that just pass tool calls through, ToolMesh adds what production deployments actually need:

• Credential Security — secrets injected at execution time, never in prompts or LLM client configs
• Authorization — fine-grained user → plan → tool control (OpenFGA)
• Input & Output Gating — JS policies block confidential data and filter responses
• Audit Trail — every tool call recorded with structured logging or queryable SQLite

The Six Pillars

Try the demo

Want to try ToolMesh before installing? Connect to our public demo instance — no Docker, no config, no API keys:

demo.toolmesh.io — Hacker News APIs via ToolMesh. Works with Claude Desktop, Claude Code, and ChatGPT. Login: dadl / toolmesh.

Quickstart

# Clone
git clone https://github.com/DunkelCloud/ToolMesh.git
cd ToolMesh

# Configure
cp .env.example .env
# IMPORTANT: Set a password — without it, all requests are rejected:
#   TOOLMESH_AUTH_PASSWORD=my-secret-password
# Or set an API key for programmatic access:
#   TOOLMESH_API_KEY=my-api-key

# Optional: local overrides (build locally, enable OpenFGA, HTTPS proxy, ...)
# cp docker-compose.override.yml.example docker-compose.override.yml
# # then edit docker-compose.override.yml — picked up automatically by Docker Compose

# Start (fine-grained authz is in bypass by default; the password/API key
# above is still required — without it every request is rejected)
docker compose up -d

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

# MCP endpoint: http://localhost:8123/mcp
# Note: Most MCP clients require HTTPS — see TLS section below

TLS (important)

ToolMesh itself 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:

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

Connect to Claude Desktop

Add to your Claude Desktop MCP config:

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

For local development without TLS proxy:

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

Connect to 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.

Authentication

ToolMesh supports two authentication methods that can be used independently or together. All OAuth state (tokens, auth codes, clients) is persisted in Redis and survives server restarts.

OAuth 2.1 (Interactive Login)

Define users in config/users.yaml with bcrypt-hashed passwords:

users:
  - username: admin
    password_hash: "$2a$10$..."
    company: dunkelcloud
    plan: pro
    roles: [admin]

Generate password hashes with any bcrypt-capable utility:

htpasswd -nbBC 10 "" "my-password" | cut -d: -f2

For single-user setups, TOOLMESH_AUTH_PASSWORD still works as a fallback. Configure the identity with TOOLMESH_AUTH_USER, TOOLMESH_AUTH_PLAN, and TOOLMESH_AUTH_ROLES (defaults: owner, pro, admin).

API Keys (Programmatic Access)

Define API keys in config/apikeys.yaml with bcrypt-hashed keys:

keys:
  - key_hash: "$2a$10$..."
    user_id: claude-code-user
    company_id: dunkelcloud
    plan: pro
    roles: [tool-executor]

Each key maps to a distinct user identity with its own plan and roles, which flow through to OpenFGA authorization.

For single-key setups, TOOLMESH_API_KEY still works as a fallback. The same TOOLMESH_AUTH_USER, TOOLMESH_AUTH_PLAN, and TOOLMESH_AUTH_ROLES variables control the identity.

DCR Rate Limiting

Dynamic Client Registration is rate-limited to 5 registrations per hour per IP to prevent abuse.

Authorization Mode

OPENFGA_MODE controls whether OpenFGA authorization is enforced:

Start with bypass to get running quickly, then switch to restrict after bootstrapping OpenFGA.

Security posture at startup

ToolMesh is secure-by-default: it ships with no individual default that relaxes a control silently. At boot it logs a single security-posture summary that lists every control still in a relaxed state (missing auth credential, authz bypass, open CORS, debug tools) together with how to harden it. In the default production posture these are logged at WARN; set TOOLMESH_DEV=true on a local-development machine to report the same facts once at INFO so the warnings don't become background noise. TOOLMESH_DEV changes only the log level of this summary — it never relaxes a setting on its own.

Configuration

See docs/configuration.md for all environment variables.

Timeout tuning

Increase these for backends that need more time (e.g. browser-based web fetchers):

TOOLMESH_MCP_TIMEOUT=180
TOOLMESH_EXEC_TIMEOUT=180

Logging

ToolMesh uses structured logging via slog. The default level is info. Set LOG_LEVEL=debug to trace the full MCP request/response flow when diagnosing a problem — but note that debug logs include complete request URLs and payloads, so for query-string API keys the credential ends up in the log. Keep debug off in production. Per-backend debug files, log formats, and all logging variables are documented in docs/configuration.md.

Metrics (Prometheus)

ToolMesh exposes Prometheus metrics on a separate listener (default host port 9090) — login counts by method and result, tool-call rates by backend and outcome, and a latency histogram with REST-tuned buckets. The endpoint is unauthenticated, so the Compose file binds the host port to 127.0.0.1 by default (reachable locally and from Prometheus on the same Docker network, never from a public interface). Set TOOLMESH_METRICS_HOST=0.0.0.0 only if you scrape from another host and have firewalled the port yourself.

Configure via TOOLMESH_METRICS_PORT, TOOLMESH_METRICS_ENABLED, and TOOLMESH_METRICS_LABEL_TOOL in .env. See docs/metrics.md for the full schema, example PromQL queries, and a sample scrape configuration.

Debug tools (opt-in)

Set TOOLMESH_DEBUG_TOOLS=true in .env to expose two diagnostic MCP tools — debug_echo (returns size and SHA-256 of the supplied payload, no backend) and debug_generate (produces a printable string of N bytes). Use them to probe transport-level size limits between the calling LLM and ToolMesh, or to verify round-trip byte integrity. Off by default; intended for development and incident triage, not production.

Architecture