Grok MCP — Agenten-Skills-Referenz
Verwenden Sie diese Datei, um zu entscheiden, welches Tool aufgerufen werden soll, welches Modell verwendet werden soll und wann Grok gar nicht aufgerufen werden soll.
Es gibt keine Standardmodelle – Sie übergeben model bei jedem Aufruf und wählen es bewusst aus:
das günstigste Modell, das die Aufgabe erledigen kann; erhöhen Sie nur, wenn die Qualität nicht ausreicht.
Wann Grok MCP vs. selbst erledigen
| Aufgabe | Grok MCP verwenden | Selbst erledigen |
|---|---|---|
| Benutzer fragt explizit nach Grok | ✅ immer der Anfrage nachkommen | — |
| Ein Bild generieren oder bearbeiten | ✅ immer | ✗ die meisten Modelle können keine Bilder generieren |
| Ein lokales Dateibild analysieren | ✅ agent(model=..., image_paths=[...]) | ✗ erfordert Datei auf der Festplatte |
| Große Codebasis-Analyse (>200K Token) | ✅ agent(model=<großer-Kontext>, tools=["read"]) | ✗ Kontextlimit |
| Ihre Antwort mit Groks vergleichen | ✅ beide aufrufen | ✅ beide aufrufen |
| Allgemeiner Text / Denken (unaufgefordert) | ✗ unnötige Kosten | ✅ bevorzugen |
| Codegenerierung (unaufgefordert) | ✗ es sei denn, Ihr aktuelles Modell ist nicht verfügbar | ✅ bevorzugen |
Standardregel: zuerst selbst erledigen. Greifen Sie auf Grok zurück, wenn:
- Der Benutzer explizit nach Grok fragt (z. B. „ask Grok“, „use Grok“, „generate with Grok“)
- Ihr aktuelles Modell die Aufgabe nicht erledigen kann (Bildgenerierung, lokale Dateiansicht, Kontext erschöpft)
- Der Benutzer bittet darum, Ihre Antwort mit Groks zu vergleichen
Modellauswahl – Ihre Entscheidung, jeder Aufruf
Jedes Tool, das ein Grok-Modell ausführt (agent, read mit einer Frage, shell, search,
generate_image*) erfordert model. Es gibt keine Rollen, keine Standardeinstellungen, keinen auto-Router.
Ein fehlendes oder unbekanntes Modell schlägt sofort mit der Liste der gültigen Optionen fehl.
Woher die Optionen kommen: Die Beschreibung jedes Tools listet den aktuellen xAI-Katalog auf –
ID, Kontextfenster, Preis pro 1 M Token (normal und gecached) und [images] für Modelle, die
Bildeingabe akzeptieren. Die Liste wird von der live xAI-API beim Serverstart gefüllt;
list_models(refresh=true) ruft den Katalog erneut ab, meldet, was sich geändert hat, und aktualisiert die
Tool-Beschreibungen. Hardcoden Sie niemals einen Modellnamen oder Preis aus dem Gedächtnis – lesen Sie die Liste.
Rollentags. Der Server markiert Modelle aus dem Live-Katalog, niemals nach Namen – so überlebt die Richtlinie
unten Modellaustausche: cheapest (niedrigster Preis), flagship (neueste Generation,
tiefgründigste, teuerste), code (für Code optimiert). Wählen Sie nach Tag und nach den angezeigten Preisen.
Standardrichtlinie – günstig starten, nur bei Nachweis eskalieren:
- Routinearbeit (Fragen, Zusammenfassungen, Extraktion, Klassifikation, Code-Änderungen, Datei-Review)
→ das
cheapest-Modell,reasoning_effort="low"wo das Modell es akzeptiert. - Eskalieren Sie auf
flagshipnur, wenn die Antwort eines günstigen Laufs eindeutig unzureichend war oder die Aufgabe eine tiefe mehrschrittige Analyse über viele Dateien hinweg ist. Nicht „um sicherzugehen“. - Lange oder tool-intensive Läufe:
tools=["read"]+ benannte Dateien,background=Trueund ein explizitesmax_cost_usd, das Sie aus der Schätzung unten ausgewählt haben – verlassen Sie sich niemals auf den Serverstandard. - Lesen Sie das Ergebnis:
cost_usd,stoppedundhint. Einhintbedeutet, dass der Lauf vorzeitig endete oder teuer für ein Flaggschiff war – folgen Sie ihm (wiederholen Sie mitcheapest, grenzen Sie die Aufgabe ein), anstatt denselben Aufruf zu wiederholen.
| Bedarf | Wählen |
|---|---|
| Eingabe größer als ~200K Token | ein Modell, dessen Kontextfenster passt – ctx prüfen |
| Bildeingabe | ein mit [images] gekennzeichnetes Modell |
| Bildgenerierung | mit dem günstigsten Bildmodell iterieren, endgültige Darstellung auf einem qualitativ hochwertigen |
Kostenkontrolle – obligatorisch für jeden agent()- / read- / shell- / search-Aufruf
1. Zuerst schätzen und angeben. Vor dem Aufruf dem Benutzer eine Zeile schreiben:
Schätzung: ~<N>K Eingabe-Token, ~<R> Runden, <Modell> → ~$<X>. Für einen winzigen
Einzelaufruf (eine kurze Frage) reicht eine Klausel („~2K Token, <$0.01“). Berechnen Sie es aus
den Preisen in der Tool-Beschreibung (niemals aus dem Gedächtnis):
- Einzelschuss (kein
tools):Eingabe-Token × Eingabe-Preis + erwartete Ausgabe × Ausgabe-Preis(1 Token ≈ 4 Zeichen; Reasoning-Token werden als Ausgabe abgerechnet). - Tool-Schleife: jede Runde sendet die gesamte Konversation erneut, daher steigen die Kosten mit den Runden. Verwenden Sie
Runden × durchschnittlicher Kontext × gecachter Preisplus die neuen Token und Ausgaben jeder Runde. Früherecost_usd-Werte aus dieser Sitzung sind die beste Kalibrierung – bevorzugen Sie sie gegenüber der Theorie. - Unsicher? Nehmen Sie die Obergrenze: Sie wird sowieso als
max_cost_usdübergeben.
2. Über 2 $ benötigen Sie die Zustimmung des Benutzers. Wenn die Schätzung 2 $ übersteigt, rufen Sie NOCH NICHT auf: zeigen Sie die Schätzung, das Modell und was gewonnen wird gegenüber einem günstigeren Lauf, und warten Sie auf ein explizites Ja. Die Zustimmung deckt nur diese Aufgabe ab, nicht spätere. Bei oder unter 2 $ fahren Sie ohne Nachfrage fort.
3. Immer max_cost_usd übergeben: Schätzung + ~30 % Spielraum, gedeckelt auf 2 $, es sei denn, der Benutzer
hat mehr akzeptiert (dann höchstens das Akzeptierte). Der GROK_MAX_COST_USD des Servers (standardmäßig 2,5 $) ist eine harte Obergrenze, kein Budget: ein höherer max_cost_usd wird darauf gedeckelt, sodass ein Lauf, der mehr benötigt, aufgeteilt werden muss oder der Operator die Obergrenze erhöhen muss.
4. Immer melden, was der Auftrag verbraucht hat. Nach jedem abgeschlossenen Aufruf – einschließlich eines Hintergrundauftrags,
der mit get_job abgeholt wird – dem Benutzer mitteilen: Modell, cost_usd und Token
(prompt / cached / completion / reasoning), plus iterations und stopped. Tun Sie dies auch,
wenn die Kosten winzig sind, und auch, wenn ein Lauf fehlgeschlagen oder vorzeitig beendet wurde. Ein noch running-Auftrag hat
noch keine Kosten – sagen Sie dies, und melden Sie sie dann, wenn er abgeholt wird. Wenn die tatsächlichen Kosten die Schätzung um mehr als ~50 % übersteigen, sagen Sie dies ebenfalls.
reasoning_effort (low/medium/high, einige Modelle auch none) gilt pro Aufruf und wird an die
API übergeben. Die Unterstützung variiert je nach Modell (der Katalog sagt nicht, welche): einige lehnen es ab, andere
lehnen none ab. Wenn Sie es nicht setzen, läuft ein flagship-Modell mit low anstelle seiner eigenen (teuren) Standardeinstellung, und jedes andere Modell verwendet seine eigene Standardeinstellung; wenn ein Modell den Parameter ablehnt, verwirft der Server die Standardeinstellung dafür. Setzen Sie es explizit (high), wenn Tiefe wichtig ist – ein expliziter Wert wird immer unverändert gesendet, und eine Ablehnung wird als API-Fehler zurückgegeben.
| Aufgabe | Modell |
|---|---|
| Kurze Frage, Zusammenfassung, Extraktion, Klassifikation | günstigstes Modell in der Liste |
| Codegenerierung / Refactoring | ein Code-Modell, falls aufgeführt, sonst ein günstiges allgemeines Modell |
| Tiefgehende Analyse, mehrschrittiges Denken, Überprüfung vieler Dateien | das neueste Flaggschiff (höchste Version) |
| Eingabe größer als ~200K Token | ein Modell, dessen Kontextfenster passt – ctx prüfen |
| Bildeingabe | ein mit [images] gekennzeichnetes Modell |
| Bildgenerierung | mit dem günstigsten Bildmodell iterieren, endgültige Darstellung auf einem qualitativ hochwertigen |
Tool → Modell-Kurzreferenz
agent(prompt, model, tools?, image_paths?, system?, conversation?, file_paths?, reasoning_effort?, max_iterations?, max_seconds?, max_cost_usd?, background=False)
Das eine Tool zum Senden von Text (und Bildern) an Grok.
| Parameter | Standard | Hinweise |
|---|---|---|
model | erforderlich | siehe Modellauswahl |
tools | [] | Arbeitsbereich-Tools, die Grok selbst aufrufen darf: read, write, shell, fetch, search. Unbekannter Name → Fehler sofort |
image_paths | — | lokale Bilder, die mit dem Prompt gesendet werden (Modell muss [images] sein); müssen für den Server sichtbar sein – siehe Pfade |
max_iterations | 100 | Modellrunden in der Tool-Schleife (Server-Obergrenze – Sie können sie nur senken) |
max_seconds | 1800 | Wanduhrzeit-Budget des Laufs (Server-Obergrenze) |
max_cost_usd | 2.5 | geschätztes USD-Budget des Laufs (Server-Obergrenze – ein höherer Wert wird gedeckelt) |
conversation | — (zustandslos) | Aufgabenname "<Projekt>/<Aufgabe>", z. B. "grok-mcp/security-audit" – behält den Kontext über die Aufrufe einer Aufgabe hinweg; Grok ruft den Verlauf bei Bedarf ab (get_recent_history/search_history). Neue Aufgabe → neuer Name; einmaliger Aufruf → weglassen (kein Verlauf gespeichert; ein Hintergrundauftrag behält sein Ergebnis trotzdem einige Tage). Das Projekt-Präfix ist wichtig: über HTTP kann der Server Projekte nicht unterscheiden. ≤ 200 Zeichen, keine Steuerzeichen |
file_paths | — | Dateiinhalte, die serverseitig eingefügt werden (Sie wählen die Dateien) |
reasoning_effort | low bei flagship, sonst Modellstandard | pro Aufruf; ein expliziter Wert wird unverändert gesendet |
background | false | gibt sofort {job_id} zurück; mit get_job(job_id) abholen. Nicht erforderlich für lange Läufe – siehe Grenzen |
Unbekannte Parameter werden zurückgewiesen mit der Liste der gültigen.
Gibt zurück (hübsches JSON):
{
"answer": "...",
"model": "grok-4.3",
"reasoning_effort": "low",
"tokens": {"prompt": 6909, "cached": 576, "completion": 49, "reasoning": 141},
"cost_usd": 0.0085,
"tool_calls": [{"tool": "read", "args": {"path": "README.md"}, "result_chars": 22463}],
"iterations": 2,
"stopped": "answer",
"hint": "nur vorhanden, wenn der Lauf vorzeitig endete oder teuer für ein Flaggschiff war"
}
stopped sagt, wie die Schleife endete: answer (normal), max_iterations, context (Fenster fast
voll), loop (derselbe Tool-Aufruf wiederholt), time (max_seconds) oder cost (max_cost_usd).
In jedem Fall läuft die letzte Runde ohne Tools, sodass answer immer enthält, was Grok aus dem Gesammelten schließen konnte – Arbeit wird nie verworfen.
Grenzen (Server-Umgebungsvariablen, Standardwerte)
| Grenze | Standard | Umgebungsvariable | Was passiert |
|---|---|---|---|
| Dauer des Vordergrundaufrufs | 60 s | GROK_FOREGROUND_TIMEOUT | der Aufruf wechselt in den Hintergrund: Sie erhalten {job_id, status: "running", note} – mit get_job abholen. Nichts geht verloren; Sie erreichen nie ein Client-Timeout |
| Laufdauer | 1800 s | GROK_JOB_MAX_SECONDS / max_seconds | endgültige Antwort, stopped: "time" |
| Laufkosten | 2,5 $ | GROK_MAX_COST_USD / max_cost_usd | endgültige Antwort, stopped: "cost" |
| Modellrunden | 100 | GROK_MAX_ITERATIONS / max_iterations | endgültige Antwort, stopped: "max_iterations" |
| Eingabe (Prompt + file_paths + Bilder) | 60 % des Modellfensters | GROK_INPUT_MAX_RATIO | vor jedem API-Aufruf zurückgewiesen, wobei Modelle genannt werden, deren Fenster passt |
| Ein Tool-Ergebnis | 15 % des Fensters | GROK_TOOL_RESULT_MAX_RATIO | Grok erhält stattdessen „Ergebnis zu groß – Zeilenbereich oder grep lesen“ |
| Gesamte Konversation | 80 % des Fensters | GROK_CONTEXT_MAX_RATIO | alte Ergebnisse einmalig gekürzt, dann neue verweigert, dann stopped: "context" |
| Shell-Befehl | 240 s | GROK_SHELL_TIMEOUT | Befehl abgebrochen, Fehler an Grok zurückgegeben |
Pfade
Mit dem Docker-Setup sieht der Server nur seine eingehängten Verzeichnisse (das Arbeitsverzeichnis und
ASSETS_DIR): image_paths, file_paths und Pfade, die Grok liest, müssen dort leben – Host /tmp
oder Scratchpad-Pfade sind unsichtbar; kopieren Sie die Datei zuerst in das Arbeitsverzeichnis. Ein stdio-Server sieht,
was sein Benutzer sehen kann, begrenzt durch GROK_READ_ALLOWED_PATHS, falls gesetzt. Ein Pfad, den der Server
nicht sehen kann, wird sofort mit der Liste der sichtbaren Wurzeln zurückgewiesen.
Automatischer Projektkontext: Wenn der Server innerhalb eines Git-Projekts läuft (stdio), fügt
agent()die erkannte Sprache und das Framework vor der Systemaufforderung ein. Im Docker-Setup wird nichts injiziert. Wennsystembereits mit[Projektkontext]beginnt, wird die Injektion übersprungen.
Lassen Sie Grok seinen eigenen Kontext sammeln. Lesen Sie Dateien nicht selbst und fügen Sie sie in den Prompt ein –
übergeben Sie tools=["read"] (fügen Sie shell für git log/grep/Testläufe hinzu) und beschreiben Sie, was
betrachtet werden soll. Dateiinhalte gelangen dann nie in Ihren Kontext:
agent(prompt="Überprüfe src/grok_mcp/tools/agent.py und chat.py auf doppelte Logik.",
model="<flagship aus der Liste>", tools=["read", "shell"])
Begrenzen Sie das Lesen. Nennen Sie die Dateien (oder ein enges Verzeichnis) im Prompt – „lies, was du brauchst“
über ein ganzes Repository hinweg führt dazu, dass ein Lauf 1,7 M Token erreicht. Bei großen Dateien weisen Sie Grok an, Code mit
shell grep -n zu lokalisieren und nur Zeilenbereiche zu lesen (read mit offset/limit).
Verwenden Sie file_paths stattdessen, wenn Sie bereits genau wissen, welche Dateien wichtig sind (ein Roundtrip, keine Schleife).
Lange Läufe und Kosten. Jede Runde sendet die gesamte Konversation erneut; xAI cached das unveränderte Präfix
automatisch (tokens.cached, ca. 75 % günstiger abgerechnet), sodass Runden hauptsächlich für das Neue bezahlen.
Das Kürzen alter Ergebnisse kostet einen Cache-Fehler. Ein dritter identischer Tool-Aufruf wird verweigert; ein fünfter beendet
die Schleife. Ein langer Aufruf kommt einfach als {job_id} nach 60 s zurück – dann get_job abfragen;
background=True überspringt nur diese erste Minute des Wartens.
Bilder. agent(prompt="Was zeigt dieser Screenshot?", model=..., image_paths=["<Arbeitsverzeichnis>/shot.png"]) – die Datei muss sich in einem Verzeichnis befinden, das der Server sieht (siehe Pfade).
Stellen Sie eine spezifische Frage pro Aufruf; kombinieren Sie mit tools, wenn das Bild mit Code verglichen werden muss.
generate_image(prompt, output_path, model, aspect_ratio?, resolution?, ref_image_paths?)
model ist erforderlich – die Tool-Beschreibung listet Bildmodelle mit ihrem Preis pro Bild auf.
Kostendisziplin:
- Iterieren Sie mit dem günstigsten Bildmodell, bis der Prompt stimmt, und wechseln Sie dann nur für die endgültige Darstellung zu einem qualitativ hochwertigeren Modell.
- Gibt
{path, model, prompt, format}zurück.
output_path muss ein absoluter Pfad sein. Übergeordnete Verzeichnisse werden automatisch erstellt.
Mit Referenzbildern (Modelle der Qualitätsstufe übertragen Stil besser):
- Übergeben Sie
ref_image_paths, wenn Stilkonsistenz mit einem vorhandenen Bild wichtig ist. Es akzeptiert bis zu 3 absolute Pfade in der Reihenfolge – der Prompt kann sie positionsbezogen ansprechen, z. B. „Geometrie vom ersten, Randfigur vom zweiten“. Jeder von Ihnen übergebene Pfad wird weitergeleitet; nichts wird stillschweigend verworfen. - Die modellspezifische Obergrenze (3 für die aktuellen Bildmodelle) wird von xAI durchgesetzt, deren Meldung wörtlich ausgegeben wird, wenn Sie sie überschreiten.
- Referenzdateien werden anhand ihrer Magic-Bytes per MIME-Sniffing erkannt, sodass ein vorheriges Ergebnis unabhängig von der Erweiterung, unter der es gespeichert wurde, direkt als Referenz zurückgegeben werden kann.
aspect_ratio(Standardwert"1:1") undresolution(Standardwert"1k", auch"2k") gelten wie ohne Referenzen. Die Ausgabe erbt nicht die Proportionen des Referenzbildes – ein 16:10-Referenzbild ergibt dennoch ein Quadrat, es sei denn, Sie geben etwas anderes an. Übergeben Sie daher beide explizit, wann immer Sie mehr als ein 1k-Quadrat benötigen.
Kostenvergleich: Ihr aktuelles Modell vs. Grok
Für genaue Preise Ihres aktuellen Modells überprüfen Sie die aktuellen Preise Ihres Anbieters.
Kurzreferenz: Nützliche MCP-Konzepte
| Konzept | Beschreibung |
|---|---|
list_models(refresh=true) | Ruft den xAI-Modellkatalog erneut ab, meldet Änderungen und aktualisiert Tool-Beschreibungen |
get_job(job_id) | Holt das Ergebnis eines Hintergrundauftrags (einschließlich Kosten, Token, Stoppgrund) |
get_recent_history(limit=10) | Zeigt die letzten Konversationen des Benutzers aus dem Speicher |
search_history(query) | Durchsucht den Konversationsverlauf nach einer Abfrage |
read(path, offset?, limit?) | Liest eine Datei mit optionalem Offset und Limit (für große Dateien) |
shell(command) | Führt einen Shell-Befehl aus (mit Timeout und Kill bei Überschreitung) |
fetch(url) | Ruft eine URL ab (für Webinhalte) |
search(query) | Führt eine Websuche durch (wenn konfiguriert) |
Best Practices
- Schätzen Sie immer zuerst die Kosten, bevor Sie einen Grok-Aufruf tätigen.
- Verwenden Sie immer
max_cost_usd, um Budgetüberschreitungen zu vermeiden. - Beginnen Sie mit dem günstigsten Modell, eskalieren Sie nur bei Bedarf.
- Überlassen Sie Grok das Sammeln des Kontexts (übergeben Sie
tools, nicht vorab gelesene Dateiinhalte). - Begrenzen Sie das Lesen auf bestimmte Dateien oder Verzeichnisse, um Kosten zu sparen.
- Verwenden Sie
background=Truefür lange Läufe (über 60 s) oder wenn Sie sofort eine Antwort benötigen. - Melden Sie die Kosten nach jedem Lauf, auch wenn sie gering sind.
- Befolgen Sie die Hinweise (
hint) – sie sagen Ihnen, ob der Lauf vorzeitig endete oder teuer war.
Fehlerbehebung
| Problem | Lösung |
|---|---|
| Modell nicht gefunden | Überprüfen Sie list_models() auf verfügbare Modelle |
| Kosten überschritten | Erhöhen Sie max_cost_usd oder teilen Sie die Aufgabe auf |
| Bild nicht sichtbar | Stellen Sie sicher, dass der Pfad in einem vom Server sichtbaren Verzeichnis liegt |
| Lauf zu lang | Verwenden Sie background=True, oder setzen Sie max_seconds und max_iterations |
| Tool nicht verfügbar | Überprüfen Sie die Tool-Beschreibung auf gültige Tool-Namen |
Sicherheitshinweise
- Grok hat nur Zugriff auf die Tools, die Sie mit
toolsübergeben. - Shell-Befehle haben ein Timeout (standardmäßig 240 s) und werden bei Überschreitung abgebrochen.
- Dateipfade sind auf sichtbare Verzeichnisse beschränkt (
GROK_READ_ALLOWED_PATHS). - Konversationen sind zustandslos, es sei denn, Sie verwenden
conversation. - Kosten sind durch
max_cost_usdundGROK_MAX_COST_USDbegrenzt.