Remote MCP (Claude.ai Browser & Co)

Du willst Claude im Browser — oder jeden anderen MCP-fähigen Client — direkt auf deine Brains zugreifen lassen: lesen, suchen, schreiben. Ohne SSH-Konfig, ohne lokalen Agent, ohne dass du die Tool-Calls selbst in den Chat kopierst.

Dafür gibt's den Remote-MCP-Endpoint /api/mcp — HTTPS, Bearer-Token, stateless. Claude.ai's Custom Connectors (Beta) sprechen genau dieses Protokoll.

Unterschied zur stdio-Variante: stdio-MCP (per SSH + gts-mcp-Binary) ist für Agenten auf der gleichen Maschine oder über SSH erreichbare Server — Claude Desktop, Claude Code, OpenClaw. Der Remote-MCP-Endpoint ist für alles, was über HTTPS kommen muss — Browser, Webhooks, Dritt-Clients.

Was ist verfügbar

Dieselben Tools wie der stdio-MCP:

Tool Was es macht
instance_info Gibt Typ + Slug der verbundenen Instanz zurück
brain_list Listet Brains (mit Filter nach Kategorie / Tag)
brain_read Liest ein Brain komplett (Frontmatter + Body)
brain_search Volltext-Suche über alle sichtbaren Brains
brain_history Git-Commits für ein Brain
brain_write Erstellt oder updatet ein Brain (schema-validiert, atomic-committed)
brain_capture Quick-Capture in die Inbox

Schreibende Tools haben dieselben Guards wie im Web-UI: Schema-Validierung, Write-Lock, Autor = der Admin der den Token besitzt.

Setup in Claude.ai (Browser)

1. Token generieren (einmalig)

Im GTS: Einstellungen → Remote MCP (Claude.ai) → Neuen Token generieren.

Der Token wird genau einmal angezeigt. Kopieren (Passwort-Manager!), weil wir ihn danach nur noch als Hash haben.

2. Custom Connector anlegen

In Claude.ai (muss Pro/Team/Enterprise sein):

  • Settings → Connectors → Custom Connector (Beta)
  • Name: beliebig, z.B. Mein Brain
  • Remote MCP Server URL: deine Instance-URL plus /api/mcp, z.B. https://gu-brain.kuble.com/api/mcp
  • Erweiterte Einstellungen → Authentifizierung: Bearer Token
  • Token einfügen → Hinzufügen

3. Im Chat nutzen

Neuer Chat → Tool-Picker öffnen → brain_*-Tools anhaken. Dann einfach fragen:

„Welche Projekte sind bei Kunde Axa aktiv?" — Claude ruft brain_search, dann brain_read für Treffer, zitiert zurück.

„Leg ein neues Projekt-Brain „nori-v4" für Kuble an mit Status active und Budget 120k." — Claude ruft brain_write, Commit landet in deinem Git.

Setup für andere MCP-Clients

Der Endpoint ist Streamable-HTTP-MCP, stateless. Jeder Client der diese Spec spricht funktioniert. Beispiel: Cursor, Continue, dein eigenes Python-Script mit dem @modelcontextprotocol/sdk.

Für einen Test-Request aus der Shell:

TOKEN="gts_…"
URL="https://gu-brain.kuble.com/api/mcp"

# Tool-Liste abfragen
curl -s -X POST "$URL" \
  -H "authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
  | jq

Token-Management

  • Mehrere Tokens pro Admin erlaubt — du kannst z.B. einen Token pro Client (Claude.ai, Cursor, Test-Script) generieren und gezielt widerrufen.
  • Widerrufen: in den Settings auf „Widerrufen" klicken — der Token ist ab sofort blockiert, Client bekommt 401.
  • Verlust: Token vergessen / Gerät verloren → widerrufen + neu generieren. Alte Tokens kannst du nie wieder einsehen (nur Hash in DB).
  • Audit: jeder tools/call über Remote-MCP landet im Audit-Log unter /history → Source mcp.

Sicherheits-Notizen

  • Token-Format: gts_<64 hex>, 32 Byte Entropie. Intern als HMAC-SHA256(GTS_AUTH_SECRET, token) gespeichert.
  • Nur Admin-Scope: ein Remote-MCP-Token wirkt mit den Rechten des Admins, der ihn erstellt hat. Auf Admin-Kategorie-Brains greift der übliche allowed_connections-Check (entspricht stdio-MCP).
  • CORS: /api/mcp gibt nur Access-Control-Allow-Origin: https://claude.ai frei. Andere Browser-Clients müssen die gleiche Origin haben oder der Check wird server-seitig umgangen (curl/Python ignoriert CORS).
  • Transport: ausschließlich HTTPS in Produktion. Lokal (Docker auf localhost:3100) ist HTTP ok, Claude.ai erreicht dann aber deinen Laptop nicht — braucht public URL (Hetzner + Traefik, siehe Self-Hosting).

Fehlerbilder

401 UNAUTHORIZED → Token falsch, abgelaufen oder widerrufen. Neu generieren.

CORS-Fehler im Browser → Nur Claude.ai (https://claude.ai) ist whitelisted. Andere Origins musst du manuell in /api/mcp/route.ts ergänzen.

Tools erscheinen nicht im Claude-Chat → Connector ist ggf. nicht aktiviert für den Workspace. In Claude.ai den Connector manuell einschalten und neuen Chat starten.

brain_write kommt mit Schema-Fehler zurück → Dieselben Regeln wie im Web-UI: type + date Pflicht für source, customer Pflicht für projekt, etc. Schema-Referenz in SCHEMAS.md.

Was nicht geht (noch)

  • OAuth: aktuell nur Bearer-Token. Für öffentliche Multi-User-Szenarien (fremde User sollen sich via OAuth ihr eigenes Brain verbinden können) bräuchte es einen OAuth-Flow. Heute: ein Admin → ein/viele Tokens.
  • Session-State / Streaming-Tools: der Endpoint ist stateless. Langlaufende Tool-Calls mit Progress-Events werden nicht gestreamt, sondern synchron bis Abschluss gehalten. Für kurze Reads + Writes reicht das; bei sehr grossen brain_search-Ergebnissen kann's einen Timeout geben.