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 — 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: "<SHA-256 of the key, 64 hex characters>"
    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.

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 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

See docs/architecture.md for the full architecture documentation.

                          ┌─────────────────────────────────┐
                          │          ToolMesh               │
                          │                                 │
                          │  Redis · OpenFGA · Audit        │
                          │  Credential Store · JS Gate     │
                          │                                 │
AI Agent ──MCP──────────▶ │   AuthZ ▸ Creds ▸ Gate ▸ Exec  │
                          │                                 │
                          └──┬──────┬───────┬───────┬───────┘
                             │      │       │       │
                          MCP Client  .dadl   .dadl   .dadl
                             │      │       │       │
                             ▼      ▼       ▼       ▼
                          MCP     Stripe  GitHub  Vikunja
                          Server   API     API     API

Adding an External MCP Server

Create or edit config/backends.yaml:

backends:
  - name: memorizer
    transport: http
    url: "https://memorizer.example.com/mcp"
    api_key_env: "MEMORIZER_API_KEY"

Set the credential as an environment variable:

CREDENTIAL_MEMORIZER_API_KEY=sk-mem-xxxxx

Tools from each backend are exposed with a prefix (e.g. memorizer_retrieve_knowledge). Credentials are injected by the Executor at runtime via the CredentialStore — the LLM never sees API keys.

REST Proxy Mode (DADL)

When an MCP server doesn't expose an endpoint you need, describe it in a .dadl file and ToolMesh calls the REST API directly — no wrapper server needed. Both modes run in parallel.

Add a REST backend to config/backends.yaml:

backends:
  - name: vikunja
    transport: rest
    dadl: /app/dadl/vikunja.dadl
    url: "https://vikunja.example.com/api/v1"

For internal services with private IPs or self-signed certificates:

backends:
  - name: internal-api
    transport: rest
    dadl: internal.dadl
    url: "https://192.168.1.50:8443/api"
    allow_private_url: true    # allow private/loopback addresses (default: true)
    tls_skip_verify: true      # accept self-signed certificates (default: false)

Want Claude to list GitHub issues? Here's all it takes:

tools:
  list_issues:
    method: GET
    path: /repos/{owner}/{repo}/issues
    description: "List issues for a repository"
    params:
      owner: { type: string, in: path, required: true }
      repo:  { type: string, in: path, required: true }
      state: { type: string, in: query }

ToolMesh handles auth, pagination, retries, and error mapping. DADL supports bearer tokens, OAuth2, session auth, API keys, automatic pagination, retry with backoff, response transformation, composite tools, and more.

For the full spec, examples, and the community registry, see dadl.ai. The fastest way to create a .dadl file is asking any LLM that knows the format.

Code Mode

Connect 15 MCP servers to a single AI agent? Without ToolMesh, that simply does not work — the context window fills up, the client chokes. Code Mode makes it possible.

Instead of exposing hundreds of individual tool definitions (50,000+ tokens), ToolMesh exposes two meta-tools: discover_tools and execute_code. The LLM gets compact TypeScript interfaces (~1,000 tokens) and writes JavaScript against them:

const repos = await toolmesh.github_list_repos({ sort: "updated" });
const issues = await toolmesh.github_list_issues({
  owner: repos[0].owner.login,
  repo: repos[0].name,
  state: "open"
});

Multiple API calls in a single round-trip. ToolMesh parses the code, extracts tool calls, and routes them through the full execution pipeline.

Extension Model

ToolMesh uses a registry-based extension model inspired by Go's database/sql driver pattern. Three component types are extensible via init() registration:

Enterprise extensions (InfisicalStore, VaultStore, Compliance-LLM, etc.) are planned and will be included via Go build tags: go build -tags enterprise ./cmd/toolmesh.

See docs/architecture.md for details.

Who's behind this

ToolMesh is built and maintained by Axel Dunkel at Dunkel Cloud GmbH — a German company building infrastructure that connects AI agents to real systems. ToolMesh and DADL grew out of the production cloud and edge infrastructure we've run for businesses for years, so this isn't a side project behind an anonymous handle: it runs in our own stack, and the same people who answer [email protected] write the code.

The companion DADL registry currently ships 27 community API descriptions covering ~3,300 generated tools — from a 4-tool Hacker News reader to a 608-tool NetBox DCIM/IPAM surface — each with a visible API-coverage percentage so you can see exactly how complete it is.

• 🌐 Website: toolmesh.io
• 📖 DADL spec & registry: dadl.ai
• 🐛 Security contact: [email protected] (see SECURITY.md)

Contributing

See CONTRIBUTING.md.

License

Apache 2.0 — Copyright 2025–2026 Dunkel Cloud GmbH