Erste Schritte: ToolMesh per Docker Compose starten
ToolMesh läuft als einzelne Go-Binary oder Docker-Container. Es stellt einen MCP-Server bereit, mit dem sich KI-Agenten verbinden.
Voraussetzungen
Abschnitt betitelt „Voraussetzungen“- Docker und Docker Compose
- Ein KI-Agent, der MCP spricht (Claude Desktop, Claude Code, Claude.ai oder ein beliebiger MCP-Client)
- Optional: ein Reverse-Proxy für TLS (Caddy, Cloudflare Tunnel, nginx)
Schnellstart
Abschnitt betitelt „Schnellstart“# Repository klonengit clone https://github.com/DunkelCloud/ToolMesh.gitcd ToolMesh
# Konfiguration erstellencp .env.example .envÖffnen Sie .env und setzen Sie mindestens eine Authentifizierungsmethode:
# Für interaktiven Login (Claude Desktop, Claude.ai):TOOLMESH_AUTH_PASSWORD=my-secure-password
# Für programmatischen Zugriff (Claude Code, Skripte):TOOLMESH_API_KEY=my-api-keyOhne Passwort oder API-Key werden alle Anfragen abgelehnt.
Autorisierung ist aktiv, ohne Setup. Das Passwort oder der API-Key von oben darf jedes Tool aufrufen. Jeder andere Aufrufer bekommt nichts, bis ein Grant ihn nennt. Wie Sie anderen Benutzern, Rollen oder Plänen Zugriff auf ausgewählte Backends oder Tools geben, steht unter Autorisierung.
# ToolMesh startendocker compose up -d
# Prüfen, ob es läuft (Standard-Port: 8123)curl http://localhost:8123/healthDer MCP-Endpunkt ist unter http://localhost:8123/mcp erreichbar.
TLS (Wichtig)
Abschnitt betitelt „TLS (Wichtig)“ToolMesh liefert reines HTTP aus. Die meisten MCP-Clients — einschließlich Claude Desktop — erfordern HTTPS und lehnen http://-URLs ab. Ein TLS-terminierender Reverse-Proxy vor ToolMesh ist nötig:
| Option | Einsatzzweck |
|---|---|
| Caddy | Selbstgehostet mit öffentlicher Domain — automatische Let’s-Encrypt-Zertifikate |
| Cloudflare Tunnel | Keine offenen Ports nötig, TLS ohne Konfiguration |
| nginx / Traefik | Bereits im Stack vorhanden |
Läuft der Proxy in einem anderen Container oder auf einer anderen Maschine, gehört seine eigene Adresse in TOOLMESH_TRUSTED_PROXIES (bei einem Container eine fest vergebene, nicht das Compose-Netz), damit ToolMesh seine Login-Limits je Client zählt und nicht je Proxy; ein Proxy auf demselben Host braucht nichts. Siehe Client-Adresse.
Für die lokale Entwicklung kann TLS umgangen werden, indem claude_desktop_config.json manuell bearbeitet wird (die GUI erzwingt https://).
KI-Agent verbinden
Abschnitt betitelt „KI-Agent verbinden“Claude Desktop
Abschnitt betitelt „Claude Desktop“Zur Claude Desktop MCP-Konfiguration (claude_desktop_config.json) hinzufügen:
{ "mcpServers": { "toolmesh": { "url": "https://toolmesh.example.com/mcp" } }}Für lokale Entwicklung ohne TLS-Proxy:
{ "mcpServers": { "toolmesh": { "url": "http://localhost:8123/mcp" } }}Claude.ai (Custom Connector)
Abschnitt betitelt „Claude.ai (Custom Connector)“ToolMesh unterstützt OAuth 2.1 mit PKCE S256 für Remote-Zugriff. Benutzer werden in config/users.yaml konfiguriert, die öffentliche HTTPS-URL dient als MCP-Endpunkt. Sobald users.yaml existiert, dürfen Plan pro und Rolle admin jedes Tool aufrufen und Plan free jedes Lese-Tool; andere Pläne oder Rollen erhalten ihre Tools über Grants in config/authz.yaml.
Claude Code
Abschnitt betitelt „Claude Code“Claude Code verbindet sich per API-Key. Setzen Sie TOOLMESH_API_KEY in der .env und fügen Sie den MCP-Endpunkt hinzu:
claude mcp add -t http -H "Authorization: Bearer MY_API_KEY" -s user toolmesh http://localhost:8123/mcpBackend hinzufügen
Abschnitt betitelt „Backend hinzufügen“Backends werden in config/backends.yaml konfiguriert.
MCP-Backend (einen bestehenden MCP-Server proxyen)
Abschnitt betitelt „MCP-Backend (einen bestehenden MCP-Server proxyen)“backends: - name: memorizer transport: http url: "https://memorizer.example.com/mcp" api_key_env: "MEMORIZER_API_KEY"Die Zugangsdaten als Umgebungsvariable in .env setzen:
CREDENTIAL_MEMORIZER_API_KEY=sk-mem-xxxxxZugangsdaten werden zur Laufzeit injiziert — das LLM sieht nie API-Keys.
Sollen die Zugangsdaten aus der .env und aus der Umgebung des Containers verschwinden, ist CREDENTIAL_STORE=command zu setzen: ToolMesh nimmt sie dann, und auch TOOLMESH_AUTH_PASSWORD oder TOOLMESH_API_KEY, aus einem Befehl wie einer sops-Entschlüsselung oder vault kv get und hält sie nur im Arbeitsspeicher. Mit ergosum wird der Schlüssel, der sie öffnet, nur auf der Maschine freigegeben, an die er gebunden ist. Siehe Credential-Stores.
REST-Backend (via DADL)
Abschnitt betitelt „REST-Backend (via DADL)“Statt einen MCP-Wrapper-Server zu bauen, kann die REST-API deklarativ in einer .dadl-Datei beschrieben werden:
backends: - name: github transport: rest dadl: /app/dadl/github.dadl url: "https://api.github.com"Der Name des Eintrags bestimmt, welche Credentials das Backend lesen darf, hier CREDENTIAL_GITHUB_*. Braucht eine DADL Credentials oder Hosts darüber hinaus, weist ToolMesh das Backend beim Laden ab und loggt die Zeile, die zu ergänzen ist; siehe Bindung an Credentials und Hosts.
DADL-Dateien gibt es in der DADL Registry oder können mit dem LLM generiert werden:
„Erstelle eine DADL für die GitHub-API — Repos auflisten, Issues öffnen und Pull Requests erstellen.”
Nächste Schritte
Abschnitt betitelt „Nächste Schritte“- Architektur — die Ausführungs-Pipeline verstehen
- DADL — REST-APIs ohne Code beschreiben
- Konfiguration — alle Umgebungsvariablen
- Authentifizierung — OAuth 2.1, API-Keys, Multi-User