Getting started

Diese Seite führt Sie durch die Registrierung der MCP-(Model Context Protocol)-Services bei einem KI-Client und den ersten authentifizierten Tool-Aufruf. Die gehosteten Endpunkte sind auf der Seite Deployments aufgeführt.

Schritt 1 — Registrieren Sie den Server bei Ihrem KI-Client

Sie müssen sich nur einmal registrieren. Dieselbe Registrierung bedient jeden Tenant; das Tenant-Routing geschieht pro Tool-Aufruf.

Claude Code (CLI)

Claude Code 1.0+ spricht HTTP MCP nativ. Registrieren Sie mit claude mcp add:

# Generic form — replace mcp.example.com with the hosted URL for your cluster
claude mcp add --transport http --scope user octomesh https://mcp.example.com/mcp

# Production examples
claude mcp add --transport http --scope user octomesh-prod-1 https://mcp.prod-1.octo-mesh.com/mcp
claude mcp add --transport http --scope user octomesh-prod-2 https://mcp.prod-2.octo-mesh.com/mcp

Scope-Optionen:

Scope	Effekt	Gut für
--scope user	In jedem Projekt verfügbar	Remote- / gemeinsam genutzte Endpunkte
--scope local	Nur im aktuellen Projekt	Projektspezifische Endpunkte
--scope project	In .mcp.json im Repo eingecheckt	Teams, die sich dasselbe Remote-MCP teilen

Die Registrierung verifizieren:

claude mcp list
# octomesh:         https://mcp.example.com/mcp            (HTTP) - ✓ Connected
# octomesh-prod-1:  https://mcp.prod-1.octo-mesh.com/mcp   (HTTP) - ✓ Connected

Starten Sie Ihre Claude-Code-Sitzung neu, damit der Tool-Katalog aufgezählt wird.

Claude Desktop

Claude Desktop unterstützt HTTP MCP ebenfalls über seine Konfigurationsdatei:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "octomesh": {
      "type": "http",
      "url": "https://mcp.example.com/mcp"
    },
    "octomesh-prod-1": {
      "type": "http",
      "url": "https://mcp.prod-1.octo-mesh.com/mcp"
    }
  }
}

Jede Registrierung erhält innerhalb von Claude Desktop ihren eigenen Tool-Namespace – mcp__octomesh__*, mcp__octomesh-prod-1__* –, sodass Sie mehrere Umgebungen nebeneinander betreiben können. Starten Sie die Desktop-App nach dem Bearbeiten der Datei neu.

Schritt 2 — Authentifizieren

Es gibt zwei Möglichkeiten, eine MCP-Sitzung zu authentifizieren. Interaktives OAuth ist der Standard für Claude Code und Claude Desktop; der Device Flow bleibt als Fallback und für Headless-Clients verfügbar.

Option A — Interaktives OAuth (empfohlen)

Spezifikationskonforme MCP-Clients (Claude Code 2.x, Claude Desktop) authentifizieren sich gegen die im Server integrierte OAuth-Discovery – kein Tool-Aufruf nötig:

1. Führen Sie in Claude Code /mcp aus und wählen Sie den OctoMesh-Server. Der Client entdeckt den Identity Service über RFC 9728 Protected Resource Metadata und registriert sich selbst als Client über RFC 7591 Dynamic Client Registration (keine vorkonfigurierte client_id).
2. Es öffnet sich ein Browserfenster mit der OctoMesh-Anmeldung. Da die Registrierung tenant-agnostisch ist, zeigt der Identity Service zuerst die Seite zur Tenant-Discovery – geben Sie Ihre E-Mail ein, wählen Sie Ihren Tenant und melden Sie sich wie gewohnt an.
3. Zurück in Claude Code zeigt die Verbindung ✓ Connected; die Tokens werden pro MCP-Sitzung gespeichert und automatisch aktualisiert.

Dynamisch registrierte Clients heißen octo-dcr-*, sind serverseitig hart eingeschränkt (nur Loopback-Redirects, PKCE, kein Secret, serverseitig festgelegte Scopes, begrenzte Lebensdauer) und laufen automatisch ab. Deployments können den Registrierungsendpunkt mit OCTO_IDENTITY__DYNAMICCLIENTREGISTRATION__ENABLED=false deaktivieren; verwenden Sie in diesem Fall Option B.

Option B — Device Flow über das authenticate-Tool

Bitten Sie Ihren KI-Assistenten, authenticate aufzurufen:

Authenticate me to tenant my-tenant.

Das Tool gibt eine Verifizierungs-URL und einen User-Code zurück. Öffnen Sie die URL in Ihrem Browser, geben Sie den Code ein und schließen Sie die Anmeldung ab. Bitten Sie den Assistenten dann, check_auth_status aufzurufen – es bestätigt, dass die Sitzung authentifiziert ist, und speichert die Tokens.

Äquivalentes rohes JSON-RPC:

{ "tool": "authenticate",       "parameters": { "tenantId": "my-tenant" } }
// → { verificationUri: "https://identity.…/device", userCode: "XXXX-YYYY", ... }

{ "tool": "check_auth_status",  "parameters": {} }
// → { isAuthenticated: true, expiresInSeconds: 3600, ... }

octo-mcpServices-device ist der Identity-Server-Client, der für diesen Flow verwendet wird; er wird beim Serverstart automatisch registriert.

Schritt 3 — Tätigen Sie Ihren ersten Aufruf

Alles, was Sie mit octo-cli tun können, können Sie den Assistenten in natürlicher Sprache bitten zu tun. Drei gute erste Aufrufe:

Wer bin ich?

Who am I logged in as?

Ruft whoami auf und gibt Ihren Namen, Ihre E-Mail, Ihre Rollen und die Tenants zurück, auf die Sie Zugriff haben.

Welche Tenants kann ich administrieren?

List my tenants.

Ruft list_tenants auf. Nützlich, bevor Sie beginnen, tenant-bezogene Tools auszuführen.

Installierte Blueprints in einem Tenant auflisten:

List all installed blueprints in tenant acme.

Ruft list_blueprint_installations mit tenantId: "acme" auf.

Schritt 4 — Tenant-Routing verstehen

Der Server ist bezüglich Tenants zustandslos. Jedes tenant-bezogene Tool akzeptiert einen optionalen tenantId-Parameter, aufgelöst in dieser Prioritätsreihenfolge:

1. Tool-Parameter tenantId (explizit, bevorzugt)
2. URL-Pfadsegment am Legacy-Endpunkt /{tenantId}/mcp (abwärtskompatibel)
3. Fehler, falls keines angegeben wird

Best Practice: Registrieren Sie eine Server-URL – /mcp (ohne Tenant) – und übergeben Sie tenantId pro Aufruf. Das lässt eine einzelne Sitzung in einer Konversation zwischen Tenants wechseln.

Tenants ohne erneute Anmeldung wechseln

Ein Access-Token ist immer an genau einen operierenden Tenant gebunden (tenant_id-Claim). Wenn ein Tool-Aufruf auf einen anderen Tenant zielt, beschafft der Server transparent ein Token für diesen Tenant über RFC 8693 Token Exchange gegen den Identity Service – vorausgesetzt, Ihr Benutzer hat dort tenant-übergreifenden Zugriff (ein ExternalTenantUserMapping; siehe Cross-Tenant Authentication). Die Rollen werden im Ziel-Tenant neu aufgelöst, sodass ein Wechsel niemals Rollen über Tenants hinweg mitträgt.

Sie können auch explizit wechseln:

Switch to tenant other-tenant.

Dies ruft switch_tenant auf, das den Austausch durchführt, das Ziel-Tenant-Token für die Sitzung zwischenspeichert und die Rollen meldet, die Sie dort innehaben. Ist der tenant-übergreifende Zugriff für den Ziel-Tenant nicht bereitgestellt, fällt der Server auf eine Device-Flow-Anmeldung (authenticate) gegen diesen Tenant zurück.

Schritt 5 — Destruktive Operationen benötigen confirm: true

Über MCP gibt es keine interaktive Abfrage. Jedes Delete-/Destroy-/Rollback-/Uninstall-Tool verweigert die Ausführung, sofern Sie nicht confirm: true übergeben. Beispiel:

{
  "tool": "delete_tenant",
  "parameters": {
    "tenantId": "octosystem",
    "childTenantId": "scratch-tenant",
    "confirm": true
  }
}

Ohne confirm: true gibt der Aufruf IsSuccess: false und ErrorMessage: "Refusing to delete '...' without confirm=true." zurück. KI-Assistenten sind darauf trainiert, dies zu lesen und Sie zuerst zu fragen – genau das gewünschte Verhalten.

Was Sie als Nächstes lesen sollten

• Tool reference – jedes verfügbare Tool, nach Familie gruppiert
• Deployments – gehostete Endpunkte und wie man sie jeweils registriert
• Troubleshooting – Authentifizierungsfehler, abgelaufene Sitzungen, häufige Fehlermeldungen