Zum Inhalt springen

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.

  • 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)
Terminal-Fenster
# Repository klonen
git clone https://github.com/DunkelCloud/ToolMesh.git
cd ToolMesh
# Konfiguration erstellen
cp .env.example .env

Öffnen Sie .env und setzen Sie mindestens eine Authentifizierungsmethode:

Terminal-Fenster
# 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-key

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

Terminal-Fenster
# ToolMesh starten
docker compose up -d
# Prüfen, ob es läuft (Standard-Port: 8123)
curl http://localhost:8123/health

Der MCP-Endpunkt ist unter http://localhost:8123/mcp erreichbar.

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:

OptionEinsatzzweck
CaddySelbstgehostet mit öffentlicher Domain — automatische Let’s-Encrypt-Zertifikate
Cloudflare TunnelKeine offenen Ports nötig, TLS ohne Konfiguration
nginx / TraefikBereits 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://).

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

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 verbindet sich per API-Key. Setzen Sie TOOLMESH_API_KEY in der .env und fügen Sie den MCP-Endpunkt hinzu:

Terminal-Fenster
claude mcp add -t http -H "Authorization: Bearer MY_API_KEY" -s user toolmesh http://localhost:8123/mcp

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:

Terminal-Fenster
CREDENTIAL_MEMORIZER_API_KEY=sk-mem-xxxxx

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

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