ki-grok/09-mcp-server-und-externe-tools.md

Kapitel 9

MCP-Server und externe Tools

Kern in einem Satz: MCP hängt externe Tools an denselben Agent-Loop – mächtig für GitHub, Issue-Tracker, DBs – und verdoppelt Trust-, Secret- und Scope-Fragen.

---

9.1 Was MCP ist (ohne Protokoll-Roman)

{width=90%}

MCP (Model Context Protocol) = Standard, mit dem Server dem Client Tools anbieten. Grok startet oder verbindet Server; das Modell entdeckt Tools und ruft sie auf – parallel zu Built-ins (read_file, Shell, …).

Beispiel-Server	Typische Tools
GitHub	Issues, PRs, Code-Search
Linear/Jira	Tickets lesen/schreiben
Postgres/Filesystem	Queries / scoped FS
Internes API-Gateway	Firmenspezifische Aktionen

Wie der Loop wirkt: Prompt → Modell will z. B. Issue anlegen → search_tool / use_tool → Server führt aus → Ergebnis zurück in den Kontext. Permissions, Always-approve, Deny-Regeln und Hooks gelten auch hier (Kapitel 13, 8).

Siehe modelcontextprotocol.io fürs Protokoll; dieses Kapitel ist Nutzung.

---

9.2 Konfiguration: stdio vs. HTTP

Primär in ~/.grok/config.toml unter [mcp_servers.<name>], projektskopiert in .grok/config.toml.

stdio (lokaler Prozess)

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]
env = { }  # Secrets lieber ${VAR} – siehe unten
enabled = true
startup_timeout_sec = 120   # Default oft 30; Cold-Start npx/uvx eher 120 (wie in vorlagen/)
tool_timeout_sec = 120
tool_timeouts = { slow_op = 300 }

Cold-Start npx/uvx braucht oft mehr als 30s Startup – per Server oder global (Gegenstück: beispiele/configs/mcp.filesystem.beispiel.toml):

export GROK_MCP_STARTUP_TIMEOUT_SECS=120
# oder Claude-kompatibel MCP_TIMEOUT in ms

HTTP / SSE (remote)

[mcp_servers.remote-api]
url = "https://mcp.example.com/api"
headers = { "Authorization" = "Bearer ${INTERNAL_MCP_TOKEN}" }

Native url-Form bevorzugen (Grok spricht HTTP/SSE/OAuth direkt) – nicht unnötig npx mcp-remote davorsetzen.

---

9.3 CLI: Server verwalten ohne TOML-Yoga

grok mcp list
grok mcp list --json

# stdio: alles nach -- ist Server-Command
grok mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/dir

# Env wiederholbar mit -e
grok mcp add postgres -e DATABASE_URL=postgres://localhost/mydb -- npx -y @modelcontextprotocol/server-postgres

# Remote
grok mcp add --transport http sentry https://mcp.sentry.dev/mcp
grok mcp add --transport http api https://mcp.example.com/mcp \
  --header "Authorization: Bearer ${INTERNAL_MCP_TOKEN}"
grok mcp add --transport sse linear https://mcp.linear.app/sse

grok mcp remove github
grok mcp enable name         # persistiert (u. a. disabled_mcp_servers)
grok mcp disable name
grok mcp doctor              # alle
grok mcp doctor github       # einer
grok mcp doctor --json

Scope:

Flag	Zieldatei
default / --scope user	~/.grok/config.toml
--scope project	.grok/config.toml (team-commitbar)

list markiert Project-Server mit (project). Namenskonflikt user vs. project: project ersetzt den Server komplett (kein Field-Merge). Remove bei Doppeldefinition: --scope angeben.

Server-Namen: nur Letters, Numbers, Hyphen, Underscore.

---

9.4 Project-Scope und Precedence

Grok walked CWD → Git-Root und lädt .grok/config.toml je Level:

Location	Priorität
~/.grok/config.toml	niedrig
<repo>/.grok/config.toml	mittel
<cwd>/.grok/config.toml	hoch

Was du heute legst: Eintrag in <cwd>/.grok/config.toml (oder Repo-Root) schlägt User-Global für denselben Server-Namen. Project-Config liefert typischerweise [mcp_servers], [plugins], [permission] – viele andere Sektionen nur user-global (Kapitel 14).

Repo-Trust: Project-MCP/LSP/Hooks hängen am Folder-Trust (trusted_folders.toml, /hooks-trust, --trust). Untrusted Repo → Server starten nicht „heimlich“.

---

9.5 Tool-Namen und Aufruf im Agent

Namespace:

filesystem__read_file
github__create_issue
linear__save_issue

Im Loop:

1. search_tool – Tools über Server finden (Schema!).
2. use_tool – qualifizierten Namen + Input laut Schema.

Praxis-Prompt:

Nutze MCP GitHub: suche offene Bugs mit Label "payments".
Keine Issues schließen. Liste Nummer + Titel.
Zuerst search_tool, dann use_tool – erfinde keine Tool-Namen.

Warum search_tool erzwingen? Verhindert halluzinierte Tool-APIs und falsche Parameter.

Große Tool-Results: Truncation (Default ~20 000 Bytes), Spill unter Session-mcp/. Override:

[mcp]
max_output_bytes = 40000

Env: GROK_MAX_MCP_OUTPUT_BYTES / MAX_MCP_OUTPUT_BYTES. Precedence: requirements > env > repo .grok/config.toml > user > default.

---

9.6 Runtime: /mcps-Modal

• Slash: /mcps (auch über Extensions-Modal /plugins → Tab MCP)
• Space enable/disable
• Expand: Tool-Liste
• r refresh nach Config-Edit
• i OAuth
• a add / x remove (mit Confirm)

OAuth-Tokens: ~/.grok/mcp_credentials.json (owner-only 0600). Dieselbe Sorgfalt wie auth.json (Kapitel 2).

---

9.7 Kompatibilität: Claude, Cursor, .mcp.json

Source	Ort	Gate
Native	config.toml	immer
Claude	~/.claude.json etc.	[compat.claude] mcps
Cursor	.cursor/mcp.json	[compat.cursor] mcps
Standard	Project .mcp.json (cwd→root)	Import-Marker-Logik

Merge-Priorität bei Namenskonflikt: config.toml > Claude > Cursor > .mcp.json.
grok inspect zeigt Origin-Tags ([cursor], [claude]).

---

9.8 Secrets und Sicherheit

Achtung: Jedes MCP-Tool ist Code + oft Credentials + Side Effects. Always-approve + freies GitHub-MCP in einem fremden Repo ist ein Incident mit besserer UX.

Do:

• Secrets als ${ENV} in Config, nie committed
• Project-MCP nur in trusted Repos
• Deny-Regeln für destruktive MCP-Tools (MCPTool(sales__delete_*) – Kapitel 13)
• Scope Filesystem-Server auf ein erlaubtes Directory
• OAuth-Hosts mit Full-Disk-Encryption

Don't:

• Production-DB-URLs mit Write im Alltag
• Unbekannte Marketplaces + sofort --trust
• Tokens in Tickets/Chat pasten
• MCP „nur kurz global“ und vergessen

Subagents erben default connected Parent-MCP (Kapitel 5) – spawne Write-fähige Kinder bewusst.

---

9.9 Beispiel-Setups (kopierbar)

Hosted HTTP (OAuth nach Connect)

[mcp_servers.linear]
url = "https://mcp.linear.app/mcp"
enabled = true

[mcp_servers.sentry]
url = "https://mcp.sentry.dev/mcp"
enabled = true

Nach Config: /mcps → r → bei Bedarf i für OAuth.

Intern mit Env-Header

[mcp_servers.internal-tools]
url = "https://mcp.internal.example.com/mcp"
enabled = true
headers = { "Authorization" = "Bearer ${INTERNAL_MCP_TOKEN}" }

Project-Filesystem (eng)

# .grok/config.toml – nur nach Team-Review committen
[mcp_servers.docs-fs]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "./docs"]
enabled = true

Vorlagen-Index: beispiele/configs/ (wachsend), vorlagen/config.toml.beispiel.toml.

---

9.10 Praxis-Sessions

Session 1 – Server adden und doctor

grok mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem "$(pwd)/docs"
grok mcp doctor filesystem
grok mcp list

grok

Welche MCP-Server sind aktiv? Nenne 3 Tools vom filesystem-Server
über search_tool. Noch nichts Destruktives.

Session 2 – Read-only Nutzung

Mit filesystem-MCP: liste Markdown-Dateien unter docs/.
Keine Writes. Zusammenfassung in 5 Bullets.

Erfolg: Qualifizierte Tool-Namen im Scrollback; Diff im Repo unverändert.

Session 3 – GitHub/Issue-Tracker (wenn konfiguriert)

Suche offene Issues mit Label bug, max 5.
Nur lesen. Keine Kommentare, keine Status-Änderungen.

Permission-Prompts lesen – Issue create ist ein Side Effect.

Session 4 – Project vs. User Scope

grok mcp add --scope project team-docs -- npx -y @modelcontextprotocol/server-filesystem ./docs
# Secret nicht in die committed TOML:
# headers/env mit ${VAR}
git diff .grok/config.toml

Erfolg: Team sieht Server-Definition; Token bleibt in Env.

Session 5 – Disable ohne Löschen

In /mcps: Server Space disable → Agent bitten, Tool zu nutzen → erwartbar Fehler/kein Tool → wieder enable.

Session 6 – Deny-Denken (Vorschau Kap. 13)

Angenommen delete_*-Tools existieren: formuliere eine Deny-Regel
und einen PreToolUse-Hook-Matcher für server__delete_*.
Implementiere noch nichts – nur Policy-Skizze.

---

9.11 Jetzt selbst machen: MCP-Parcours (30 Minuten)

Jetzt selbst machen

1. Einen eng gescopten filesystem-MCP auf ./docs oder Temp-Dir.
2. grok mcp doctor grün/Fehler lesen und beheben (Timeout, npx).
3. Session: search_tool → use_tool, nur lesen.
4. Server disable/enable im Modal spüren.
5. Optional: einen HTTP-Server mit ${TOKEN} statt Klartext.
6. grok inspect – MCP-Origin notieren.
7. Notiere: Welches Tool bräuchte eine Deny-Regel im Team?

---

9.12 Häufige Fehler

Symptom	Ursache	Fix
Server startet nicht	Timeout / PATH / npx	doctor, Startup-Timeout erhöhen
Tools „fehlen“	disabled / untrusted project	/mcps, Folder-Trust
Auth-Fehler	OAuth nicht connected / Header	i im Modal, ${VAR} expandiert?
Halluzinierte Tools	kein search_tool	Prompt erzwingen
Riesiger Kontext	große Tool-Outputs	max_output_bytes, engere Queries
Secret im Git	Klartext in project config	${VAR}, git history prüfen
Windows npx	.cmd-Shims	Grok resolved PATHEXT; absolute Pfade ok

---

9.13 Checkliste MCP

• Server-Zweck und Scope dokumentiert
• Secrets nur Env / OAuth-Store
• Project-MCP committed ohne Tokens
• mcp doctor nach Setup
• Erste Nutzung read-only
• Deny/Hooks für destruktive Tools geplant
• Subagent-Vererbung bedacht

---

Was du jetzt kannst

• stdio- und HTTP-MCP konfigurieren und per CLI/Modal verwalten
• Tools über Namespace, search_tool und use_tool korrekt nutzen
• Project- vs. User-Scope, Trust und Secret-Hygiene anwenden
• Typische Startup-, Auth- und Halluzinations-Fallen beheben

Nächste Schritte

→ Kapitel 10 – Headless Mode, Scripting und CI: dieselbe Engine ohne TUI – mit Always-approve, Deny und sauberen Exit-Codes.