jzubielik/grok-mcp

Grok MCP — Referencia de Habilidades del Agente

Usa este archivo para decidir qué herramienta llamar, qué modelo usar, y cuándo no llamar a Grok en absoluto. No hay modelos predeterminados: pasas model en cada llamada y lo eliges deliberadamente: el modelo más barato que pueda hacer el trabajo; sube solo cuando la calidad sea insuficiente.

---

Cuándo usar Grok MCP vs. hacerlo tú mismo

Tarea	Usar Grok MCP	Hacerlo tú mismo
El usuario pide explícitamente Grok	✅ siempre respeta la solicitud	—
Generar o editar una imagen	✅ siempre	✗ la mayoría de los modelos no pueden generar imágenes
Analizar una imagen de archivo local	✅ agent(model=..., image_paths=[...])	✗ requiere archivo en disco
Análisis de código base grande (>200K tokens)	✅ agent(model=<contexto-grande>, tools=["read"])	✗ límite de contexto
Comparar tu respuesta con la de Grok	✅ llama a ambos	✅ llama a ambos
Texto / razonamiento general (sin solicitud)	✗ costo innecesario	✅ prefiere
Generación de código (sin solicitud)	✗ a menos que tu modelo actual no esté disponible	✅ prefiere

Regla predeterminada: hazlo tú mismo primero. Recurre a Grok cuando:

• El usuario pide explícitamente a Grok (por ejemplo, "pregunta a Grok", "usa Grok", "genera con Grok")
• Tu modelo actual no puede realizar la tarea (generación de imágenes, visión de archivos locales, contexto agotado)
• El usuario pide comparar tu respuesta con la de Grok

---

Elegir un modelo: tu decisión, cada llamada

Cada herramienta que ejecuta un modelo Grok (agent, read con una pregunta, shell, search, generate_image*) requiere model. No hay roles, ni valores predeterminados, ni enrutador auto. Un modelo faltante o desconocido falla de inmediato con la lista de opciones válidas.

De dónde vienen las opciones: la descripción de cada herramienta lista el catálogo actual de xAI: id, ventana de contexto, precio por 1M de tokens (normal y en caché) y [images] para modelos que aceptan entrada de imágenes. La lista se completa desde la API en vivo de xAI cuando se inicia el servidor; list_models(refresh=true) vuelve a obtener el catálogo, informa qué cambió y actualiza las descripciones de las herramientas. Nunca codifiques un nombre de modelo o precio de memoria: lee la lista.

Etiquetas de rol. El servidor marca los modelos del catálogo en vivo, nunca por nombre, por lo que la política a continuación sobrevive a los cambios de modelo: cheapest (precio más bajo), flagship (generación más nueva, más profunda, más cara), code (optimizado para código). Elige por etiqueta y por los precios mostrados.

Política predeterminada: comienza barato, escala solo con evidencia:

1. Trabajo rutinario (preguntas, resúmenes, extracción, clasificación, ediciones de código, revisión de archivos) → el modelo cheapest, reasoning_effort="low" donde el modelo lo acepte.
2. Escalar a flagship solo cuando la respuesta de una ejecución barata fue claramente insuficiente, o la tarea es un análisis profundo de varios pasos a través de muchos archivos. No "para estar seguro".
3. Ejecuciones largas o con muchas herramientas: tools=["read"] + archivos nombrados, background=True, y un max_cost_usd explícito que elegiste de la estimación a continuación: nunca confíes en el valor predeterminado del servidor.
4. Lee el resultado: cost_usd, stopped y hint. Un hint significa que la ejecución terminó temprano o fue costosa en un flagship: síguelo (reintenta en cheapest, reduce la tarea) en lugar de volver a ejecutar la misma llamada.

Necesidad	Elegir
Entrada mayor de ~200K tokens	un modelo cuya ventana de contexto encaje: verifica ctx
Entrada de imagen	un modelo marcado [images]
Generación de imágenes	iterar en el modelo de imagen más barato, render final en uno de calidad

Control de costos: obligatorio para cada llamada agent() / read / shell / search

1. Estima primero, y dilo. Antes de la llamada, escribe una línea al usuario: Estimación: ~<N>K tokens de entrada, ~<R> rondas, <modelo> → ~$<X>. Para una llamada única pequeña (una pregunta corta) una cláusula es suficiente ("~2K tokens, <$0.01"). Calcúlalo a partir de los precios en la descripción de la herramienta (nunca de memoria):

• Disparo único (sin tools): input_tokens × precio-entrada + expected_output × precio-salida (1 token ≈ 4 caracteres; los tokens de razonamiento se facturan como salida).
• Bucle de herramientas: cada ronda reenvía toda la conversación, por lo que el costo crece con las rondas. Usa rondas × contexto_promedio × precio-caché más los tokens nuevos y la salida de cada ronda. Los valores pasados de cost_usd de esta sesión son la mejor calibración: prefierelos a la teoría.
• ¿No estás seguro? Toma el límite superior: es lo que pasarás como max_cost_usd de todos modos.

2. Por encima de $2 necesitas la aceptación del usuario. Si la estimación supera $2, NO llames todavía: muestra la estimación, el modelo y qué se gana sobre una ejecución más barata, y espera un "sí" explícito. La aceptación cubre solo esa tarea, no las posteriores. Con $2 o menos, procede sin preguntar.

3. Siempre pasa max_cost_usd: estimación + ~30% de margen, limitado a $2 a menos que el usuario haya aceptado más (entonces como máximo lo que aceptaron). El GROK_MAX_COST_USD del servidor ($2.5 por predeterminado) es un límite duro, no un presupuesto: un max_cost_usd más alto está limitado a él, por lo que una ejecución que necesite más debe dividirse o el operador debe aumentar el límite.

4. Siempre informa lo que consumió el trabajo. Después de cada llamada finalizada, incluido un trabajo en segundo plano recopilado con get_job, informa al usuario: modelo, cost_usd y tokens (prompt / cached / completion / reasoning), además de iterations y stopped. Hazlo incluso cuando el costo sea mínimo, y también cuando una ejecución falló o terminó temprano. Un trabajo que aún está running no tiene costo todavía: dilo, luego infórmalo cuando se recopile. Si el costo real superó la estimación en más ~50%, dilo también.

reasoning_effort (low/medium/high, algunos modelos también none) es por llamada y se pasa a la API. El soporte varía según el modelo (el catálogo no lo indica): algunos lo rechazan, otros rechazan none. Cuando lo dejas sin establecer, un modelo flagship se ejecuta con low en lugar de su propio ( costoso) predeterminado, y cualquier otro modelo usa su propio predeterminado; si un modelo rechaza el parámetro, el servidor elimina el predeterminado para ese modelo. Establécelo explícitamente (high) cuando la profundidad importe: un valor explícito siempre se envía tal cual, y un rechazo se devuelve como error de API.

Tarea	Modelo
Pregunta rápida, resumen, extracción, clasificación	modelo más barato en la lista
Generación / refactorización de código	un modelo de código si está listado, si no, un modelo general barato
Análisis profundo, razonamiento de varios pasos, revisión de muchos archivos	el flagship más nuevo (versión más alta)
Entrada mayor de ~200K tokens	un modelo cuya ventana de contexto encaje: verifica ctx
Entrada de imagen	un modelo marcado [images]
Generación de imágenes	iterar en el modelo de imagen más barato, render final en uno de calidad

---

Referencia rápida: Herramienta → Modelo

agent(prompt, model, tools?, image_paths?, system?, conversation?, file_paths?, reasoning_effort?, max_iterations?, max_seconds?, max_cost_usd?, background=False)

La única herramienta para enviar texto (e imágenes) a Grok.

parámetro	predeterminado	notas
model	requerido	ver Elegir un modelo
tools	[]	herramientas del espacio de trabajo que Grok puede llamar por sí mismo: read, write, shell, fetch, search. Nombre desconocido → error de inmediato
image_paths	—	imágenes locales enviadas con el prompt (el modelo debe ser [images]); deben ser visibles para el servidor — ver Rutas
max_iterations	100	rondas del modelo en el bucle de herramientas (límite del servidor: solo puedes reducirlo)
max_seconds	1800	presupuesto de tiempo real de la ejecución (límite del servidor)
max_cost_usd	2.5	presupuesto estimado en USD de la ejecución (límite del servidor: un valor mayor está limitado)
conversation	— (sin estado)	nombre de la tarea "<proyecto>/<tarea>", ej. "grok-mcp/auditoría-seguridad" — mantiene el contexto entre las llamadas de una tarea; Grok extrae el historial bajo demanda (get_recent_history/search_history). Tarea nueva → nombre nuevo; llamada única → omitir (no se guarda historial; un trabajo en segundo plano aún conserva su resultado durante unos días). El prefijo del proyecto importa: a través de HTTP, el servidor no puede distinguir proyectos. ≤ 200 caracteres, sin caracteres de control
file_paths	—	contenidos de archivos inyectados del lado del servidor (tú eliges los archivos)
reasoning_effort	low en flagship, si no predeterminado del modelo	por llamada; un valor explícito se envía tal cual
background	False	devuelve {job_id} de inmediato; recopila con get_job(job_id). No es necesario para ejecuciones largas: ver Límites

Los parámetros desconocidos son rechazados con la lista de los válidos.

Devuelve (JSON bonito):

{
  "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": "solo presente cuando la ejecución terminó temprano o fue costosa en un flagship"
}

stopped indica cómo terminó el bucle: answer (normal), max_iterations, context (ventana casi llena), loop (la misma llamada de herramienta repetida), time (max_seconds) o cost (max_cost_usd). En todos los casos, la última ronda se ejecuta sin herramientas, por lo que answer siempre contiene lo que Grok pudo concluir de lo que recopiló: el trabajo nunca se descarta.

Límites (variables de entorno del servidor, predeterminados)

Límite	Predeterminado	Variable de entorno	Qué sucede
Duración de llamada en primer plano	60 s	GROK_FOREGROUND_TIMEOUT	la llamada se mueve al segundo plano: recibes {job_id, status: "running", note} — recopila con get_job. No se pierde nada; nunca alcanzas un tiempo de espera del cliente
Duración de la ejecución	1800 s	GROK_JOB_MAX_SECONDS / max_seconds	respuesta final, stopped: "time"
Costo de la ejecución	$2.5	GROK_MAX_COST_USD / max_cost_usd	respuesta final, stopped: "cost"
Rondas del modelo	100	GROK_MAX_ITERATIONS / max_iterations	respuesta final, stopped: "max_iterations"
Entrada (prompt + file_paths + imágenes)	60% de la ventana del modelo	GROK_INPUT_MAX_RATIO	rechazado antes de cualquier llamada a la API, nombrando modelos cuya ventana encaje
Un resultado de herramienta	15% de la ventana	GROK_TOOL_RESULT_MAX_RATIO	Grok recibe "resultado demasiado grande: lee un rango de líneas o usa grep" en su lugar
Toda la conversación	80% de la ventana	GROK_CONTEXT_MAX_RATIO	los resultados antiguos se recortan una vez, luego se rechazan los nuevos, luego stopped: "context"
Comando de shell	240 s	GROK_SHELL_TIMEOUT	comando terminado, error devuelto a Grok

Rutas

Con la configuración de Docker, el servidor solo ve sus directorios montados (el espacio de trabajo y ASSETS_DIR): image_paths, file_paths y las rutas que Grok lee deben estar allí: el /tmp del host o las rutas del bloc de notas son invisibles; copia el archivo primero al espacio de trabajo. Un servidor stdio ve lo que su usuario puede, limitado por GROK_READ_ALLOWED_PATHS cuando está configurado. Una ruta que el servidor no puede ver es rechazada de inmediato con la lista de raíces visibles.

Contexto automático del proyecto: cuando el servidor se ejecuta dentro de un proyecto git (stdio), agent() antepone el lenguaje y el framework detectados al prompt del sistema. No se inyecta nada en la configuración de Docker. Si system ya comienza con [Project Context], se omite la inyección.

Deja que Grok recopile su propio contexto. No leas archivos tú mismo y los pegues en el prompt: pasa tools=["read"] (agrega shell para git log/grep/ejecuciones de prueba) y describe qué debe mirar. Los contenidos de los archivos nunca entran en tu contexto:

agent(prompt="Revisa src/grok_mcp/tools/agent.py y chat.py en busca de lógica duplicada.",
      model="<flagship de la lista>", tools=["read", "shell"])

Limita la lectura. Nombra los archivos (o un directorio estrecho) en el prompt: "lee lo que necesites" en un repositorio completo es cómo una ejecución alcanza 1.7M tokens. Para archivos grandes, dile a Grok que localice el código con shell grep -n y lea solo rangos de líneas (read con offset/limit).

Usa file_paths en su lugar cuando ya sepas exactamente qué archivos importan (un viaje de ida y vuelta, sin bucle).

Ejecuciones largas y costo. Cada ronda reenvía toda la conversación; xAI almacena en caché el prefijo sin cambios automáticamente (tokens.cached, facturado ~75% más barato), por lo que las rondas pagan principalmente por lo que es nuevo. Recortar resultados antiguos cuesta una falta de caché. Una tercera llamada de herramienta idéntica es rechazada; una quinta termina el bucle. Una llamada larga simplemente regresa como {job_id} después de 60 s — luego consulta get_job; background=True solo omite ese primer minuto de espera.

Imágenes. agent(prompt="¿Qué muestra esta captura de pantalla?", model=..., image_paths=["<espacio-de-trabajo>/captura.png"]) — el archivo debe estar en un directorio que el servidor vea (ver Rutas). Haz una pregunta específica por llamada; combina con tools cuando la imagen deba compararse con código.

---

generate_image(prompt, output_path, model, aspect_ratio?, resolution?, ref_image_paths?)

model es requerido: la descripción de la herramienta lista modelos de imagen con su precio por imagen.

Disciplina de costo:

• Iterar con el modelo de imagen más barato hasta que el prompt sea correcto, luego cambiar a un modelo de mayor calidad solo para el render final.
• Devuelve {path, model, prompt, format}.

output_path debe ser una ruta absoluta. Los directorios padre se crean automáticamente.

Con imágenes de referencia (los modelos de nivel de calidad transfieren mejor el estilo):

• Pasa ref_image_paths cuando la consistencia de estilo con una imagen existente importe. Acepta hasta 3 rutas absolutas, en orden: el prompt puede dirigirse a ellas posicionalmente, ej. "geometría de la primera, personaje del borde de la segunda". Cada ruta que pasas se reenvía; no se descarta nada silenciosamente.
• El límite por modelo (3 para los modelos de imagen actuales) es aplicado por xAI, cuyo mensaje se muestra textualmente si lo superas.
• Los archivos de referencia se detectan por MIME a partir de sus bytes mágicos, por lo que un resultado anterior se puede volver a alimentar directamente como referencia independientemente de la extensión bajo la que se guardó.
• aspect_ratio (predeterminado "1:1") y resolution (predeterminado "1k", también "2k") se aplican como sin referencias. La salida no hereda las proporciones de la imagen de referencia: una referencia 16:10 aún produce un cuadrado a menos que indiques lo contrario, así que pasa ambos explícitamente siempre que necesites más que un cuadrado de 1k.

---

Comparación de costos: tu modelo actual vs. Grok

Para precios exactos de tu modelo actual, consulta el proveedor actual[truncated]...