MCP

ZeroClaw es un cliente MCP: se conecta a servidores externos de Model Context Protocol y expone sus herramientas al agente. Cada herramienta MCP tiene un espacio de nombres con el formato <server>__<tool> (por ejemplo filesystem__read_file), de modo que las herramientas de diferentes servidores nunca entran en conflicto.

Configurar MCP

El soporte de MCP está habilitado de forma predeterminada, pero no se exponen herramientas MCP externas hasta que se configure al menos un servidor bajo mcp.servers y se conceda ese servidor a un agente a través de sus mcp_bundles (consulta el ámbito de servidores por agente más abajo). Configura mediante el gateway, zerocode o zeroclaw config set:

zeroclaw config set mcp.servers.filesystem.command npx

Establece mcp.enabled = false para deshabilitar la carga de herramientas MCP sin eliminar las definiciones del servidor.

Acotación de servidor por agente (mcp_bundles)

Una entrada de [[mcp.servers]] solo define un servidor. Qué servidores conecta realmente un agente lo decide agents.<alias>.mcp_bundles, y el modelo es seguro por defecto: la omisión no otorga acceso.

• Un agente sin mcp_bundles no se conecta a ningún servidor MCP, incluso cuando mcp.servers no está vacío.
• Un bundle [mcp_bundles.<alias>] nombra los servidores que concede por su name de mcp.servers, con una lista exclude opcional. El permiso de un agente es la unión de los servidores de todos los bundles que referencia, menos cualquier nombre excluido por cualquiera de esos bundles (la denegación prevalece).
• Un alias de bundle desconocido, o un nombre de servidor de bundle que no coincide con ningún servidor configurado, no concede nada. Ambos fallan de forma cerrada y se informan como advertencias no fatales mediante la validación de la configuración, por lo que un error tipográfico restringe el acceso de un agente en lugar de ampliarlo.

[[mcp.servers]]
name = "filesystem"
command = "npx"

[mcp_bundles.files]
servers = ["filesystem"]

[agents.assistant]
mcp_bundles = ["files"]   # se conecta a `filesystem`; un agente sin esto no obtiene servidores MCP

• Los cambios de los bundles surten efecto al reiniciar la sesión. El resolvedor (Config::mcp_servers_for_agent) se ejecuta en el momento de construcción de la sesión/agente; editar [mcp_bundles.*] o agents.<alias>.mcp_bundles mientras una sesión está activa no cambia los servidores conectados de esa sesión. Finaliza y reinicia las sesiones afectadas para aplicar los nuevos permisos.

Este es el límite de conexión (qué servidores puede contactar un agente en absoluto). Los controles allowed_tools / excluded_tools de abajo son el límite de capacidad por herramienta que se aplica encima de lo que exponga un servidor concedido.

Transportes

Se accede a un servidor mediante uno de tres transportes (el campo transport):

env (stdio) y headers (http/sse) se almacenan como secretos; headers normalmente contiene el token Authorization: Bearer … para el servidor upstream.

Agrega un servidor a través del gateway, zerocode o zeroclaw config set (por ejemplo zeroclaw config set mcp.servers.filesystem.command npx). Un servidor stdio necesita command más args/env opcionales; un servidor http/sse necesita url más headers opcionales. Los comandos por campo se encuentran en la tabla de campos a continuación.

Editando servidores

Tres superficies editan la misma tabla [[mcp.servers]]:

• config.toml: edita manualmente las claves documentadas a continuación. La tabla completa se conserva al guardar.
• zerocode TUI (/config -> mcp.servers): editor por campo de primera clase. La sección muestra una fila por servidor, etiquetada con el name del servidor; entra en una fila para editar transport, command / url, headers, env y tool_timeout_secs como campos individuales. + Add crea una nueva entrada inicializada con el nombre que proporciones; eliminar de la lista de alias quita la entrada. El campo name no se edita en línea porque renombrar la clave natural durante la edición invalidaría las referencias en curso; usa el panel de control o edita config.toml a mano para renombrar por ahora.
• Panel web: actualmente renderiza mcp.servers mediante un editor de arrays JSON. Está planificada una migración a la misma interfaz por campos que usa la TUI; hasta entonces, el panel sigue siendo un editor funcional, aunque más rudimentario.

Campos del servidor

Campos por servidor ([[mcp.servers]]), generados a partir del esquema:

zeroclaw config set mcp.servers.args <value>

export ZEROCLAW_mcp__servers__args=

zeroclaw config set mcp.servers.command <value>

export ZEROCLAW_mcp__servers__command=

zeroclaw config set mcp.servers.env    # entrada enmascarada, almacenada cifrada

export ZEROCLAW_mcp__servers__env=

zeroclaw config set mcp.servers.headers    # entrada enmascarada, almacenada cifrada

export ZEROCLAW_mcp__servers__headers=

zeroclaw config set mcp.servers.max_response_bytes <value>

export ZEROCLAW_mcp__servers__max_response_bytes=

zeroclaw config set mcp.servers.name <value>

export ZEROCLAW_mcp__servers__name=

zeroclaw config set mcp.servers.pinned_resources <value>

export ZEROCLAW_mcp__servers__pinned_resources=

zeroclaw config set mcp.servers.tls_ca_cert_path <value>

export ZEROCLAW_mcp__servers__tls_ca_cert_path=

zeroclaw config set mcp.servers.tool_timeout_secs <value>

export ZEROCLAW_mcp__servers__tool_timeout_secs=

zeroclaw config set mcp.servers.transport <value>

export ZEROCLAW_mcp__servers__transport=

zeroclaw config set mcp.servers.url <value>

export ZEROCLAW_mcp__servers__url=

tool_timeout_secs es un tiempo de espera opcional por llamada; debe ser mayor que 0 y tiene un límite máximo de 600 segundos.

Confianza en CA personalizadas

Para un servidor HTTP o SSE cuyo certificado haya sido emitido por una CA privada, establece tls_ca_cert_path en una ruta absoluta que contenga uno o más certificados de CA codificados en PEM. Los certificados configurados se añaden al almacén de confianza predeterminado; la verificación de la cadena de certificados, la caducidad y el nombre de host siguen habilitadas.

Un archivo de CA con una ruta relativa, ausente, ilegible, vacío, demasiado grande, que no sea un archivo normal o no válido provoca un error de conexión irrecuperable para ese servidor. La ruta debe resolverse en un archivo normal de no más de 1 MiB. Los enlaces simbólicos se siguen, por lo que la rotación de certificados y las configuraciones de secretos montados que publican el paquete mediante un enlace simbólico funcionan según lo configurado; el archivo resuelto se valida después de abrirlo, y se rechaza un enlace simbólico que se resuelva en un directorio, dispositivo o FIFO. ZeroClaw nunca desactiva la verificación ni recurre silenciosamente a una alternativa cuando se establece este campo. La URL configurada del servidor y cualquier endpoint de mensajes anunciado por un servidor SSE deben usar https://; las URL de texto plano y las redirecciones a un protocolo inferior se rechazan antes de enviar encabezados o contenido de la solicitud. El valor se aplica cuando se inicia la sesión de MCP; reinicie la sesión afectada después de cambiarlo. Elimine el campo y reinicie la sesión para volver al almacén de confianza predeterminado. Los servidores Stdio lo ignoran.

Campos de nivel superior

zeroclaw config set mcp.deferred_loading <value>

export ZEROCLAW_mcp__deferred_loading=

zeroclaw config set mcp.servers <value>

export ZEROCLAW_mcp__servers=

Carga diferida

mcp.deferred_loading es false de forma predeterminada, por lo que las herramientas MCP configuradas se incluyen en el contexto del modelo de forma anticipada. Establécelo en true para incluir solo los nombres de las herramientas MCP en el prompt del sistema; el LLM llama a la herramienta integrada tool_search para obtener el esquema completo de una herramienta antes de invocarla. Esto mantiene reducida la ventana de contexto inicial cuando un servidor expone muchas herramientas.

Seguridad y aprobación

Las llamadas a herramientas de MCP pasan por la misma compuerta de aprobación que cualquier otra herramienta, regida por el perfil de riesgo del agente (risk_profiles.<alias>). El paso de descubrimiento tool_search se aprueba automáticamente para que la carga diferida de MCP pueda funcionar en sesiones no interactivas, pero las herramientas descubiertas desde servidores MCP siguen la política de aprobación normal:

• Con nivel de autonomía level = full, no hay solicitudes de confirmación para llamadas a herramientas (incluidas las herramientas MCP).
• De lo contrario, una llamada a una herramienta MCP solicita aprobación a menos que su nombre con prefijo (<server>__<tool>) esté en la lista auto_approve del perfil. auto_approve = ["*"] aprueba todo; una entrada exacta como auto_approve = ["filesystem__read_file"] aprueba solo esa herramienta.
• always_ask es lo inverso: un nombre (o "*") allí siempre solicita confirmación, anulando auto_approve.

Autorización: allowed_tools / excluded_tools

Las puertas de aprobación determinan cuándo una llamada a una herramienta necesita la autorización de una persona. Las puertas de autorización determinan si el agente puede llamar a una herramienta en absoluto. Ambas son independientes.

Mantén los tres controles de herramientas MCP en sus propios ejes:

Para las herramientas MCP descubiertas en tiempo de ejecución, el contrato de capacidad tiene una excepción específica de MCP:

• Si el perfil de riesgo tiene allowed_tools vacío o se omite, no se aplica ninguna restricción de autorización; cualquier herramienta descubierta (MCP o integrada) es accesible. La configuración TOML no distingue entre un campo omitido y allowed_tools = []; ambos se deserializan al mismo estado de “sin restricción de autorización” a nivel del perfil de riesgo. Si necesitas una puerta explícita de denegación total, hazlo en allowed_tools por ejecución proporcionado por quien llama (los trabajos cron y otros limitadores pasan esa lista directamente) o mediante excluded_tools, cubriendo las herramientas específicas que quieras bloquear.
• Si allowed_tools no está vacío, cualquier herramienta MCP cuyo nombre contenga __ (la convención <server>__<tool>) se admite automáticamente en la lista de अनुमति efectiva sin necesidad de aparecer allí de forma individual. Las incorporadas que no son MCP siguen necesitando una entrada exacta.
• excluded_tools siempre resta, incluso del conjunto MCP auto-admitido. Para bloquear una sola herramienta MCP como filesystem__write_file mientras se mantiene accesible el resto del servidor filesystem, colóquela en excluded_tools.

La razón: antes de esta excepción, todo agente que fijaba una lista allowed_tools para bloquear su superficie integrada perdía silenciosamente todas las herramientas MCP, incluso las que el operador configuraba explícitamente. El coste es que la lista de denegación es ahora la palanca principal del operador para bloquear capacidades destructivas de MCP bajo un perfil fijado a una lista de अनुमति.

Si quieres el patrón estricto de antes de este cambio, en el que solo admites herramientas MCP que enumeras explícitamente sin auto-admisión de __, combina una entrada explícita de allowed_tools con una entrada de excluded_tools por cada herramienta destructiva relacionada que necesites bloquear:

[risk_profiles.assistant]
allowed_tools = [
  "file_read",
  "filesystem__read_file",
]
# Bloquea el hermano destructivo que, de otro modo, se admitiría automáticamente mediante
# la excepción `__` anterior.
excluded_tools = [
  "filesystem__write_file",
]
auto_approve = [
  "filesystem__read_file",
]

La excepción de autoadmisión __ de MCP solo está delimitada por los allowed_tools del perfil de riesgo. Las listas de अनुमति por ejecución suministradas por el llamador, como allowed_tools de un trabajo cron o cualquier otra invocación restringida que pase una lista explícita al entorno de ejecución, siguen tratándose como intersecciones estrictas de listas explícitas, sin autoadmisión __ adicional. Un trabajo cron que se limite a allowed_tools = ["cron_add"] no expondrá filesystem__write_file al modelo incluso cuando el perfil de riesgo del agente, de otro modo, lo autoadmitiría mediante la convención __; la restricción por ejecución sigue siendo un límite de capacidad fiable, independientemente de cuántos servidores MCP estén configurados.

auto_approve por sí solo no oculta una herramienta al modelo; solo responde la pregunta de aprobación después de que el modelo seleccione esa herramienta. Usa tool_filter_groups para reducir el ruido del prompt y allowed_tools / excluded_tools para imponer un límite de capacidades.

Consulta Niveles de autonomía para conocer la superficie completa de campos por perfil, y la Referencia de configuración para ver todos los campos MCP y sus valores predeterminados.

MCP Resources y prompts

Además de las herramientas MCP, ZeroClaw expone recursos y prompts MCP de los servidores conectados.

Herramientas

Hay dos herramientas integradas disponibles (sujetas a la política de acceso a herramientas de tu agente):

• mcp_resources: action: "list" (opcional server, cursor) enumera recursos; action: "read" con uri (prefijado <server>__<uri>) devuelve el contenido.
• mcp_prompts: action: "list" lista los prompts; action: "get" con name (prefijado <server>__<name>) y arguments opcionales devuelve los mensajes del prompt renderizado.

Los servidores que no anuncian capacidades de resource/prompt se omiten, y las llamadas contra ellos devuelven un error claro de “no admite”.

Anclar recursos en el contexto

Cada entrada de servidor MCP acepta un campo opcional pinned_resources: una lista de URI de recursos que se leen una vez al inicio y se inyectan en el prompt del sistema. Configúralo mediante las mismas superficies de configuración que se usan para definir el servidor (el gateway, zerocode o zeroclaw config set, como se muestra en Configurar MCP), nombrando los recursos que quieres que el agente tenga siempre a mano. El campo tiene como valor predeterminado vacío, así que los servidores que no lo incluyan no se ven afectados.

El contenido fijado se lee una vez por ejecución (sin actualización en vivo) y se etiqueta como trust="untrusted-external" para que el modelo lo trate como datos, no como instrucciones.

Blobs de recursos incrustados en los resultados de las herramientas

Cuando un resultado de MCP tools/call incluye un elemento de contenido con la estructura type: "resource" y un blob anidado (base64), ZeroClaw no vuelca ese base64 en el contexto del modelo. En su lugar, materializa los bytes en el directorio uploads/ del espacio de trabajo de la sesión (con el mismo helper compartido y el límite de 10 MB que el resource.blob entrante de ACP) y reemplaza la salida de la herramienta visible para el modelo por texto de procedencia sin blob, además de un marcador [Document: …] o [IMAGE:…]. Esto se determina por la estructura del contenido, no por el nombre de la herramienta. La materialización no entrega automáticamente el archivo a los clientes de ACP; el agente sigue llamando a deliver_file cuando se necesita una entrega saliente. Consulta ingesta de blobs de ACP session/prompt.

Dado que el resultado procede de un servidor no confiable, se aplican dos límites por llamada antes de decodificar, calcular el hash o escribir cualquier blob: como máximo 64 blobs de recursos por resultado de tools/call, y un tamaño total estimado de datos decodificados de como máximo 10 MiB entre todos ellos. Un resultado que supera cualquiera de los dos límites degrada cada blob de recursos a un marcador [attachment unavailable: …] y no escribe nada en el disco, de modo que un array con muchos blobs vacíos o pequeños no puede forzar trabajo por elemento. Cada blob individual sigue estando limitado por el mismo límite de 10 MB por archivo.

A diferencia de estos presupuestos decodificados, cada servidor HTTP/SSE MCP también tiene un límite del cuerpo de respuesta a nivel de transporte, max_response_bytes, aplicado a los bytes de red codificados sin procesar antes de analizar el cuerpo, para que un servidor no pueda forzar una lectura sin límites. No es el límite decodificado de 10 MiB anterior: su valor predeterminado es 16,078,168 bytes, la expansión en base64 del agregado decodificado de 10 MiB más margen para la envoltura JSON-RPC, de modo que un blob válido cercano al límite aún llega a materializarse. Establezca max_response_bytes en un servidor para anularlo; 0 o dejarlo sin establecer usa ese valor predeterminado.

Seguridad

El contenido de recursos y prompts se origina en el servidor MCP configurado y se trata como no confiable: se envuelve con procedencia, se elimina la información sensible y se limita su longitud antes de entrar en contexto. El acceso a mcp_resources / mcp_prompts y a servidores específicos se rige por la política de acceso a herramientas de tu agente (perfil de riesgo), y se restringe correctamente al delegar en subagentes.