toolmesh — Claude Code MCP server: REST APIs as agent tools
A self-hosted gateway that sits between your agent and your systems: describe a REST API in a .dadl file and keep access, secrets and call logs under your control.
Open on GitHubWhat toolmesh does
ToolMesh sits between the AI agent and your backend. Rather than building and maintaining a wrapper server, you describe the REST methods you need in a declarative YAML .dadl file and drop it into config/dadl/. Existing MCP servers can be proxied through it as well. Writing the file by hand is optional — any model that knows the DADL format can produce one.
Inside are the layers production setups usually lack. Secrets are injected at call time, so they stay out of prompts and out of the LLM client config. Authorization is on by default: OpenFGA rules decide who may call which tool, keyed to a user, role, plan or company. JavaScript policies block confidential data before execution and strip personal data from responses. Every call lands in structured logging or a queryable SQLite store, so you can answer with SQL what an agent actually did.
Set TOOLMESH_AUTH_PASSWORD or TOOLMESH_API_KEY in .env before starting: with neither a password nor a key, the server rejects every request. ToolMesh itself speaks plain HTTP, while most MCP clients insist on HTTPS, so a TLS-terminating proxy belongs in front — Caddy, Cloudflare Tunnel, nginx or Traefik. For local development you can skip TLS by editing claude_desktop_config.json by hand. The default port is 8123 and the MCP endpoint is /mcp.
What it helps with
- wire an internal REST API into an agent without writing a wrapper server
- describe the API methods you need in a single YAML file
- give different roles different sets of tools
- keep tokens and passwords out of prompts and client configs
- reconstruct from the log what an agent called
Example prompts for the agent
- Generate a
.dadlfor the GitHub API: list repos, open issues, create pull requests - Add our billing endpoints to
config/dadl/and expose them as tools - Query the audit log for the tools the agent called in the last hour
How to install toolmesh
1Template address
The server address is a template: replace {…} or […] with your own values
2Platform CLI: remote server
claude mcp add --transport http toolmesh https://{host}:8123/mcp1Template address
The server address is a template: replace {…} or […] with your own values
2Platform CLI: remote server
codex mcp add toolmesh --url https://{host}:8123/mcp1Template address
The server address is a template: replace {…} or […] with your own values
2Config file
{
"mcpServers": {
"toolmesh": {
"url": "https://{host}:8123/mcp"
}
}
}1Template address
The server address is a template: replace {…} or […] with your own values
2Config file
{
"servers": {
"toolmesh": {
"type": "http",
"url": "https://{host}:8123/mcp"
}
}
}1Template address
The server address is a template: replace {…} or […] with your own values
2Platform CLI: remote server
gemini mcp add -t http toolmesh https://{host}:8123/mcpStep by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about toolmesh
How do I install toolmesh in Claude Code?
Run claude mcp add --transport http toolmesh https://{host}:8123/mcp, replacing the host with your own.
What does toolmesh do?
It is a gateway that turns a REST API into MCP tools from a .dadl description, adding authorization, secret injection, data filtering and a call log.
Why won't my client connect over http?
ToolMesh serves plain HTTP, and most MCP clients accept HTTPS only. Put a TLS proxy in front of it. For local development you can edit claude_desktop_config.json by hand.
