Toolmesh

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 — on by default: who may call which tool, by user, role, plan or company (OpenFGA, built in)
• 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](https://www.toolmesh.io/en/demo/) — 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, external 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 (authorization is on: the password/API key above gets every tool;

without a password or API key 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. Each entry names its key by the SHA-256 of the key:

keys:

• key_sha256: " " user_id: claude-code-user company_id: dunkelcloud plan: pro roles: [tool-executor]

Generate a key and its key_sha256:

KEY="tm_$(openssl rand -hex 32)"

printf '%s' "$KEY" | sha256sum | cut -d' ' -f1

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

Entries with a bcrypt key_hash, as files written for earlier versions have them, keep working without any change. Until its key has been used once after startup, such an entry costs a bcrypt comparison for every bearer credential that nothing else recognizes; key_sha256 is looked up directly and is meant for randomly generated keys. See docs/configuration.md for the details and for how the two forms differ.

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.

Unauthenticated Requests

A request to /mcp without a valid credential is answered 401 with a WWW-Authenticate: Bearer challenge that carries resource_metadata, as the MCP authorization specification asks. MCP clients start the OAuth flow, or refresh an expired token, on that status. Such requests are logged at INFO and counted in toolmesh_logins_total{method="anonymous"}. See docs/configuration.md.

DCR Rate Limiting

Dynamic Client Registration is rate-limited to 5 registrations per hour per IP to prevent abuse (with Redis; a Redis outage lets registrations through and is logged). A registered client that never obtains a token is forgotten after a day, and one that does after 90 days without a new token (TOOLMESH_DCR_CLIENT_TTL, TOOLMESH_DCR_CLIENT_IDLE_TTL). See docs/configuration.md.

File Broker

The file broker (upload_file, POST /files/upload, download URLs under /blobs/) can be switched off with TOOLMESH_FILE_BROKER_ENABLED=false and bounded with a quota in bytes, in total and per user (TOOLMESH_FILE_BROKER_MAX_TOTAL_BYTES, TOOLMESH_FILE_BROKER_MAX_BYTES_PER_USER). It is on and unbounded by default. See docs/configuration.md.

Login Throttling

Failed password logins are limited per account and per client address: by default 5 failures for one account from one address, 20 for one account from all addresses together, and 50 from one address across all accounts, each within 15 minutes. Beyond that the login answers 429 until the window has passed. Every failed login is logged at WARN and counted in toolmesh_logins_total{result="failure"}. Already issued tokens and API keys are not affected by a lockout. See docs/configuration.md for the variables and the reverse-proxy requirement of the per-address limits.

The number of bcrypt comparisons that run at the same time is bounded for the whole process (TOOLMESH_BCRYPT_MAX_CONCURRENT, default: half of the available CPUs), so that password logins cannot take the CPU away from everything else. See docs/configuration.md.

Authorization

Every tool call is checked, and tool listings show each caller only the tools it may call. Nothing has to be set up: ToolMesh runs OpenFGA inside its own process and keeps its data in data/authz.db.

TOOLMESH_AUTHZ_MODE selects the engine:

Grants refer to the users, roles, plans and companies from users.yaml, apikeys.yaml or the single password/API key. Without a grants file a preset applies:

For finer control, copy config/authz.yaml.example to config/authz.yaml; grants can name all tools, backends, single tools or DADL access classes (read, write, ...), denies block any of these and win over every grant, and changes take effect within seconds:

grants:

• plan: pro backends: [github, deepl]
• plan: free access: [read]
• role: support tools: [zammad_list_tickets]

denies:

• plan: pro tools: [stripe_create_refund]

An installation upgraded from a version without authorization keeps every tool open to every authenticated caller (preset open) and says so at every start, until you pick a preset or write grants. OPENFGA_MODE is deprecated: restrict maps to external, bypass to embedded. See docs/configuration.md.

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, authorization disabled or open to everyone, open CORS, debug tools, login limits switched off) together with how to harden it. In the default production posture these are log