200| :- | :- | :- | :- |200| :- | :- | :- | :- |
201| `title` | `string` | `undefined` | Título legible por humanos para la herramienta |201| `title` | `string` | `undefined` | Título legible por humanos para la herramienta |
202| `readOnlyHint` | `boolean` | `false` | Si es `true`, la herramienta no modifica su entorno |202| `readOnlyHint` | `boolean` | `false` | Si es `true`, la herramienta no modifica su entorno |
203| `destructiveHint` | `boolean` | `true` | Si es `true`, la herramienta puede realizar actualizaciones destructivas (solo significativo cuando `readOnlyHint` es `false`) |203| `destructiveHint` | `boolean` | `true` | Si es `true`, la herramienta puede realizar actualizaciones destructivas. Establece `destructiveHint: true` explícitamente en cualquier herramienta que marques como [`always_ask`](#mcpservertoolpolicy), o el clasificador del modo automático puede aprobar las llamadas a esa herramienta en lugar de tu callback `canUseTool`. No basta con dejar `destructiveHint` sin establecer, porque Claude Code trata un `destructiveHint` sin establecer como `false` cuando gestiona las llamadas `always_ask`, aunque el valor predeterminado de la especificación MCP es `true` |
204| `idempotentHint` | `boolean` | `false` | Si es `true`, las llamadas repetidas con los mismos argumentos no tienen efecto adicional (solo significativo cuando `readOnlyHint` es `false`) |204| `idempotentHint` | `boolean` | `false` | Si es `true`, las llamadas repetidas con los mismos argumentos no tienen efecto adicional (solo significativo cuando `readOnlyHint` es `false`) |
205| `openWorldHint` | `boolean` | `true` | Si es `true`, la herramienta interactúa con entidades externas (por ejemplo, búsqueda web). Si es `false`, el dominio de la herramienta es cerrado (por ejemplo, una herramienta de memoria) |205| `openWorldHint` | `boolean` | `true` | Si es `true`, la herramienta interactúa con entidades externas (por ejemplo, búsqueda web). Si es `false`, el dominio de la herramienta es cerrado (por ejemplo, una herramienta de memoria) |
206 206
630 ): Promise<SDKControlReadFileResponse | null>;630 ): Promise<SDKControlReadFileResponse | null>;
631 reloadPlugins(options?: {631 reloadPlugins(options?: {
632 holdOnCacheImpact?: boolean;632 holdOnCacheImpact?: boolean;
633 addPlugins?: SdkPluginConfig[];
633 }): Promise<SDKControlReloadPluginsResponse>;634 }): Promise<SDKControlReloadPluginsResponse>;
634 reloadSkills(): Promise<SDKControlReloadSkillsResponse>;635 reloadSkills(): Promise<SDKControlReloadSkillsResponse>;
635 reloadOutputStyles(): Promise<SDKControlReloadOutputStylesResponse>;636 reloadOutputStyles(): Promise<SDKControlReloadOutputStylesResponse>;
669| `mcpServerStatus()` | Devuelve el estado de los servidores MCP conectados como [`McpServerStatus`](#mcpserverstatus)`[]` |670| `mcpServerStatus()` | Devuelve el estado de los servidores MCP conectados como [`McpServerStatus`](#mcpserverstatus)`[]` |
670| `getContextUsage(opts?)` | Devuelve un [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse) que desglosa el uso de la ventana de contexto de la sesión por categoría, skill y herramienta. Con el `detail` predeterminado, incluye los datos que muestra `/context` en una sesión interactiva, calculados con solicitudes a la API de conteo de tokens que no aparecen en el flujo de mensajes; consulta [cómo se gestionan estas solicitudes](#sdkcontrolgetcontextusageresponse). La [opción `detail`](#sdkcontrolgetcontextusageresponse) requiere Agent SDK v0.3.257 o posterior |671| `getContextUsage(opts?)` | Devuelve un [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse) que desglosa el uso de la ventana de contexto de la sesión por categoría, skill y herramienta. Con el `detail` predeterminado, incluye los datos que muestra `/context` en una sesión interactiva, calculados con solicitudes a la API de conteo de tokens que no aparecen en el flujo de mensajes; consulta [cómo se gestionan estas solicitudes](#sdkcontrolgetcontextusageresponse). La [opción `detail`](#sdkcontrolgetcontextusageresponse) requiere Agent SDK v0.3.257 o posterior |
671| `readFile(path, options?)` | Lee un archivo del sistema de archivos de la sesión. Claude Code resuelve la ruta respecto a `cwd`; [Qué puede leer `readFile()`](#what-readfile-can-read) enumera los archivos que sirve. Pasa `{ maxBytes }` para cambiar el límite de lectura (1 MB de forma predeterminada, máximo 10 MB) y `{ encoding: 'base64' }` para archivos binarios como imágenes. Se resuelve con un [`SDKControlReadFileResponse`](#sdkcontrolreadfileresponse), o con `null` ante una denegación de permiso, un archivo inexistente o un error de transporte. Requiere TypeScript SDK v0.2.121 o posterior |672| `readFile(path, options?)` | Lee un archivo del sistema de archivos de la sesión. Claude Code resuelve la ruta respecto a `cwd`; [Qué puede leer `readFile()`](#what-readfile-can-read) enumera los archivos que sirve. Pasa `{ maxBytes }` para cambiar el límite de lectura (1 MB de forma predeterminada, máximo 10 MB) y `{ encoding: 'base64' }` para archivos binarios como imágenes. Se resuelve con un [`SDKControlReadFileResponse`](#sdkcontrolreadfileresponse), o con `null` ante una denegación de permiso, un archivo inexistente o un error de transporte. Requiere TypeScript SDK v0.2.121 o posterior |
672| `reloadPlugins(options?)` | Recarga los plugins desde el disco, para que los plugins que instales o edites durante la sesión lleguen a la sesión en ejecución. Se resuelve con un [`SDKControlReloadPluginsResponse`](#sdkcontrolreloadpluginsresponse) que enumera los comandos, subagentes y plugins de la sesión, y el estado de los servidores MCP. Requiere Agent SDK v0.2.85 o posterior. La [opción `holdOnCacheImpact`](#sdkcontrolreloadpluginsresponse) requiere Agent SDK v0.3.268 o posterior |673| `reloadPlugins(options?)` | Vuelve a cargar los plugins desde el disco, para que los plugins que instalas o editas a mitad de sesión lleguen a la sesión en ejecución. Se resuelve con un [`SDKControlReloadPluginsResponse`](#sdkcontrolreloadpluginsresponse) que enumera los comandos, subagentes, plugins y el estado de los servidores MCP de la sesión. Requiere Agent SDK v0.2.85 o posterior. La [opción `holdOnCacheImpact`](#sdkcontrolreloadpluginsresponse) requiere Agent SDK v0.3.268 o posterior. La [opción `addPlugins`](#load-more-plugin-folders-with-addplugins) requiere Agent SDK v0.3.301 o posterior |
673| `reloadSkills()` | Recarga los skills desde el disco, para que los skills que agregues o edites durante la sesión estén disponibles en la sesión en ejecución. Se resuelve con un [`SDKControlReloadSkillsResponse`](#sdkcontrolreloadskillsresponse) que enumera los skills disponibles después de la recarga. Requiere Agent SDK v0.3.163 o posterior |674| `reloadSkills()` | Recarga los skills desde el disco, para que los skills que agregues o edites durante la sesión estén disponibles en la sesión en ejecución. Se resuelve con un [`SDKControlReloadSkillsResponse`](#sdkcontrolreloadskillsresponse) que enumera los skills disponibles después de la recarga. Requiere Agent SDK v0.3.163 o posterior |
674| `reloadOutputStyles()` | Vuelve a leer los [estilos de salida](https://code.claude.com/docs/es/output-styles.md) desde el disco, para que un archivo de estilo que agregues o edites durante la sesión esté disponible en la sesión en ejecución. Se resuelve con un [`SDKControlReloadOutputStylesResponse`](#sdkcontrolreloadoutputstylesresponse) que enumera los nombres de los estilos disponibles después de la recarga. Requiere Agent SDK v0.3.261 o posterior |675| `reloadOutputStyles()` | Vuelve a leer los [estilos de salida](https://code.claude.com/docs/es/output-styles.md) desde el disco, para que un archivo de estilo que agregues o edites durante la sesión esté disponible en la sesión en ejecución. Se resuelve con un [`SDKControlReloadOutputStylesResponse`](#sdkcontrolreloadoutputstylesresponse) que enumera los nombres de los estilos disponibles después de la recarga. Requiere Agent SDK v0.3.261 o posterior |
675| `seedReadState(path, mtime)` | Marca un archivo como ya leído para que un Edit posterior no falle con `File has not been read yet`. Consulta [`seedReadState()`](#seedreadstate). Requiere TypeScript SDK v0.2.83 o posterior |676| `seedReadState(path, mtime)` | Marca un archivo como ya leído para que un Edit posterior no falle con `File has not been read yet`. Consulta [`seedReadState()`](#seedreadstate). Requiere TypeScript SDK v0.2.83 o posterior |
1135 1136
1136`cache_impact` solo está presente junto con `held: true`. `mcp_servers_added` y `mcp_servers_removed` nombran los servidores MCP de plugins que la recarga registraría o eliminaría, como nombres con alcance `plugin:<plugin>:<server>`. Los nombres los define el autor del plugin, así que valídalos antes de mostrarlos. `lsp_tool_change` indica si aplicar la recarga agregaría o eliminaría la herramienta LSP, o es `null` cuando no haría ninguna de las dos cosas. Las formas `may-` significan que la comprobación no pudo ver por completo el conjunto de plugins pendiente.1137`cache_impact` solo está presente junto con `held: true`. `mcp_servers_added` y `mcp_servers_removed` nombran los servidores MCP de plugins que la recarga registraría o eliminaría, como nombres con alcance `plugin:<plugin>:<server>`. Los nombres los define el autor del plugin, así que valídalos antes de mostrarlos. `lsp_tool_change` indica si aplicar la recarga agregaría o eliminaría la herramienta LSP, o es `null` cuando no haría ninguna de las dos cosas. Las formas `may-` significan que la comprobación no pudo ver por completo el conjunto de plugins pendiente.
1137 1138
1139#### Cargar más carpetas de plugins con `addPlugins`
1140
1141Para cargar carpetas de plugins que no estaban en la opción [`plugins`](#options) al inicio, pásalas a `reloadPlugins()` como `addPlugins`, una lista de entradas [`SdkPluginConfig`](#sdkpluginconfig) cuyo `path` es absoluto. Claude Code carga las carpetas nuevas y recarga los plugins existentes de la sesión en una sola pasada. Los servidores MCP de cada plugin añadido también se conectan, a menos que establezcas [`skipMcpDiscovery`](#sdkpluginconfig) en la entrada de esa carpeta. Requiere Agent SDK v0.3.301 o posterior y Claude Code v2.1.301 o posterior.
1142
1143Este ejemplo añade una carpeta a una consulta en ejecución `q` e imprime la ruta de instalación de cada plugin que la sesión ha cargado cuando la llamada retorna:
1144
1145```typescript theme={null}
1146const result = await q.reloadPlugins({
1147 addPlugins: [{ type: "local", path: "/opt/my-app/plugins/reports" }]
1148});
1149
1150console.log(result.plugins.map((plugin) => plugin.path));
1151```
1152
1153Si la carpeta se cargó, la lista impresa incluye `/opt/my-app/plugins/reports`, y los comandos y subagentes del plugin aparecen en `result.commands` y `result.agents`.
1154
1155Una carpeta añadida sigue formando parte de la sesión. Cuando vuelves a llamar a `reloadPlugins()`, Claude Code la recarga con los demás plugins, y no tienes que pasarla de nuevo en `addPlugins`.
1156
1157##### Cuando `reloadPlugins()` no carga las carpetas de `addPlugins`
1158
1159Si `reloadPlugins()` se rechaza, no se añade ninguna de las carpetas de `addPlugins`, así que pásalas de nuevo en `addPlugins` cuando reintentes. Cuando el rechazo tiene una de las siguientes causas, la sesión conserva los plugins que ya tenía:
1160
1161* **Un `path` relativo o una entrada mal formada**: el mensaje de error dice `add_plugins must be a list of { type: "local", path } entries with absolute paths`. Claude Code rechaza toda la lista por una sola entrada incorrecta, así que pasa cada entrada como `{ type: "local", path }` con un `path` absoluto
1162* **Un administrador ha activado [`disableSideloadFlags`](https://code.claude.com/docs/es/settings-reference#disablesideloadflags) en tu configuración administrada**: el mensaje dice `reload_plugins add_plugins is disabled by managed settings (disableSideloadFlags)`. Para cargar la carpeta, pide a ese administrador que elimine el ajuste
1163* **No se pudo reconstruir el [sandbox](https://code.claude.com/docs/es/sandboxing.md)**: con el [sandboxing](#sandboxsettings) activado, Claude Code reconstruye la configuración del sandbox para que los comandos de shell ejecutados en el sandbox no puedan escribir en las carpetas que añades. El mensaje dice `the sandbox could not be rebuilt to keep shell commands out of this folder`. Comprueba que tu [configuración del sandbox](#sandboxsettings) siga formando una configuración válida
1164
1165Si pasas `holdOnCacheImpact` y la llamada se resuelve con [`held: true`](#sdkcontrolreloadpluginsresponse), las carpetas de `addPlugins` no se añaden. Para añadirlas de todos modos, vuelve a llamar a `reloadPlugins()` con la misma lista `addPlugins` y sin `holdOnCacheImpact`.
1166
1167Cuando la llamada se resuelve sin `held: true` y una carpeta sigue faltando en `result.plugins`, empieza por comprobar estas causas:
1168
1169* **La carpeta no existe o su plugin no se pudo cargar**: `result.error_count` es `1` o más. Aun así, la carpeta sigue formando parte de la sesión. Después de corregir la carpeta, vuelve a llamar a `reloadPlugins()` para cargarla, esta vez sin incluirla en `addPlugins`
1170* **El ejecutable de Claude Code es anterior a v2.1.301**: un ejecutable anterior a v2.1.301 ignora `addPlugins` y recarga solo los plugins que la sesión ya tenía. Comprueba `claude_code_version` en el [mensaje de inicialización](#sdksystemmessage) y ejecuta un ejecutable en v2.1.301 o posterior
1171
1138### `SDKControlReloadSkillsResponse`1172### `SDKControlReloadSkillsResponse`
1139 1173
1140Tipo de retorno de [`reloadSkills()`](#query-object).1174Tipo de retorno de [`reloadSkills()`](#query-object).
1430 1464
1431#### `McpSdkServerConfigWithInstance`1465#### `McpSdkServerConfigWithInstance`
1432 1466
1467La configuración de un servidor MCP en proceso, uno que crea [`createSdkMcpServer()`](#createsdkmcpserver) y que se ejecuta dentro del proceso de tu aplicación. Es el objeto que devuelve `createSdkMcpServer()`, más una lista opcional `tools` de entradas [`McpServerToolPolicy`](#mcpservertoolpolicy) que añades tú mismo. Para exigir aprobación para las llamadas a una de las herramientas del servidor, o para denegarlas, añade una entrada que nombre la herramienta.
1468
1433```typescript theme={null}1469```typescript theme={null}
1434type McpSdkServerConfigWithInstance = {1470type McpSdkServerConfigWithInstance = {
1435 type: "sdk";1471 type: "sdk";
1436 name: string;1472 name: string;
1437 timeout?: number;1473 timeout?: number;
1474 tools?: McpServerToolPolicy[];
1438 instance: McpServer;1475 instance: McpServer;
1439};1476};
1440```1477```
1441 1478
1479Para establecer una política, propaga el objeto que devuelve `createSdkMcpServer()` en un objeto nuevo dentro de `mcpServers` y añade la lista `tools` a ese objeto nuevo. La opción `tools` del propio `createSdkMcpServer()` es una lista distinta, que contiene las definiciones de herramientas y no acepta entradas de política. La lista de políticas requiere Agent SDK v0.3.301 o posterior, y [`McpServerToolPolicy`](#mcpservertoolpolicy) describe qué hace cada valor de `permission_policy`.
1480
1481Este ejemplo aprueba de antemano todas las herramientas del servidor `records` con un comodín en `allowedTools`, y luego marca `delete_record` como `always_ask` para que las llamadas a ella vayan a `canUseTool` de todos modos. Con la anotación `destructiveHint: true`, la llamada sigue llegando al callback si la sesión se ejecuta en modo `auto`, donde de lo contrario el [clasificador](https://code.claude.com/docs/es/permission-modes.md#eliminate-prompts-with-auto-mode) del modo automático podría aprobarla.
1482
1483```typescript theme={null}
1484import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
1485import { z } from "zod";
1486
1487const deleteRecord = tool(
1488 "delete_record",
1489 "Delete a customer record by ID",
1490 { id: z.string() },
1491 async ({ id }) => ({ content: [{ type: "text", text: `Deleted record ${id}` }] }),
1492 { annotations: { destructiveHint: true } }
1493);
1494
1495const records = createSdkMcpServer({ name: "records", tools: [deleteRecord] });
1496
1497for await (const message of query({
1498 prompt: "Delete customer record 42",
1499 options: {
1500 mcpServers: {
1501 // Spread the returned config and add the policy list beside it
1502 records: {
1503 ...records,
1504 tools: [{ name: "delete_record", permission_policy: "always_ask" as const }]
1505 }
1506 },
1507 allowedTools: ["mcp__records__*"],
1508 canUseTool: async (toolName, input) => {
1509 console.log(`Approval requested for ${toolName}`);
1510 return { behavior: "allow", updatedInput: input };
1511 }
1512 }
1513})) {
1514 if (message.type === "result" && message.subtype === "success") {
1515 console.log(message.result);
1516 }
1517}
1518```
1519
1520Cuando Claude llama a la herramienta, el script imprime `Approval requested for mcp__records__delete_record` antes de que se ejecute la herramienta `delete_record`, aunque la entrada de `allowedTools` habría aprobado la llamada en otro caso.
1521
1522Para cambiar o levantar la política de una herramienta mientras la sesión se ejecuta, pasa la configuración del servidor con un nuevo valor de `tools` a [`setMcpServers()`](#mcpsetserversresult). El valor de `tools` que pases surte efecto a partir de la siguiente llamada de Claude a las herramientas de ese servidor:
1523
1524* **Una lista con entradas**: las entradas reemplazan las políticas actuales
1525* **Una lista vacía**: se borran todas las políticas del servidor
1526* **Sin clave `tools`**: las políticas actuales se mantienen
1527
1528Incluye en esa llamada tus demás servidores en proceso y cualquier servidor que haya añadido una llamada anterior a `setMcpServers()`, o la llamada los desconectará.
1529
1530#### `McpServerToolPolicy`
1531
1532Una entrada de la lista `tools` de un [`McpSdkServerConfigWithInstance`](#mcpsdkserverconfigwithinstance), que nombra una de las herramientas del servidor y establece la política de permisos para las llamadas a esa herramienta. La lista requiere Agent SDK v0.3.301 o posterior y Claude Code v2.1.301 o posterior. Un ejecutable de Claude Code más antiguo, como un ejecutable al que apuntes con `pathToClaudeCodeExecutable`, ignora la lista. En ese caso, `always_ask` y `always_deny` no se aplican, y cada llamada pasa por el [flujo de permisos](https://code.claude.com/docs/es/agent-sdk/permissions.md#how-permissions-are-evaluated).
1533
1534```typescript theme={null}
1535type McpServerToolPolicy = {
1536 name: string;
1537 permission_policy?: "always_allow" | "always_ask" | "always_deny";
1538 org_max_permission?: "allow" | "ask" | "blocked";
1539};
1540```
1541
1542| Campo | Tipo | Descripción |
1543| :- | :- | :- |
1544| `name` | `string` | El nombre simple de la herramienta tal como se pasa a [`tool()`](#tool), sin el prefijo `mcp__<server>__` |
1545| `permission_policy` | `'always_allow' \| 'always_ask' \| 'always_deny'` | La política de aprobación para las llamadas a la herramienta, [`always_ask` o `always_deny`](#permission-policy-values). `always_allow` se ignora en un servidor en proceso: para aprobar de antemano una herramienta, inclúyela en [`allowedTools`](#options) en su lugar |
1546| `org_max_permission` | `'allow' \| 'ask' \| 'blocked'` | Un límite por herramienta que establece un administrador de la organización. Se ignora en un servidor en proceso, así que déjalo sin establecer |
1547
1548##### Valores de `permission_policy`
1549
1550Elige `always_ask` para aprobar cada llamada tú mismo, o `always_deny` para bloquear la herramienta por completo:
1551
1552* **`always_ask`**: cada llamada a la herramienta [necesita aprobación](https://code.claude.com/docs/es/agent-sdk/permissions.md#how-permissions-are-evaluated), incluso si una entrada de `allowedTools` o una regla de permiso la cubre. La llamada va a tu callback `canUseTool` o a tu herramienta [`permissionPromptToolName`](#options), a menos que se resuelva antes. Un [mod](https://code.claude.com/docs/es/plugins/mods/overview.md) de un plugin que cargues [puede aprobarla antes](https://code.claude.com/docs/es/permissions.md#precedence-among-rules-hooks-and-mods). De lo contrario, en el modo `dontAsk` se deniega, y en los [modos `auto`, `plan` y `bypassPermissions`](#permission-modes-that-can-approve-an-always_ask-call) puede aprobarse antes de llegar a tu callback
1553* **`always_deny`**: una llamada a la herramienta [se deniega](https://code.claude.com/docs/es/agent-sdk/permissions.md#how-permissions-are-evaluated) en todos los modos de permisos, incluido `bypassPermissions`, pero un mod de un plugin que cargues [aún puede aprobarla](https://code.claude.com/docs/es/permissions.md#precedence-among-rules-hooks-and-mods)
1554
1555Si no pasas ni `canUseTool` ni `permissionPromptToolName`, o estableces [`permissionPrompts`](#options) en `'none'`, una llamada `always_ask` que no se resuelva antes se deniega a menos que un [hook `PermissionRequest`](https://code.claude.com/docs/es/hooks#permissionrequest) la permita.
1556
1557##### Modos de permisos que pueden aprobar una llamada `always_ask`
1558
1559En los modos `auto`, `plan` y `bypassPermissions`, una llamada a una herramienta marcada como [`always_ask`](#permission-policy-values) puede aprobarse antes de llegar a tu callback `canUseTool`. Busca el modo de tu sesión en esta lista para ver cuándo ocurre esa aprobación y qué establecer para que la llamada llegue a tu callback de todos modos:
1560
1561* **`auto`**: el [clasificador](https://code.claude.com/docs/es/permission-modes.md#eliminate-prompts-with-auto-mode) del modo automático revisa la llamada y puede permitirla. Para que todas las llamadas lleguen a tu callback en modo `auto`, establece `destructiveHint: true` en las [anotaciones](#toolannotations) de la herramienta
1562* **`plan`**: mientras el [modo automático esté disponible](https://code.claude.com/docs/es/permission-modes.md#eliminate-prompts-with-auto-mode) para la sesión, las llamadas a una herramienta `always_ask` anotada con `readOnlyHint: true` van al clasificador del modo automático, que puede permitirlas. Las llamadas a otras herramientas `always_ask` llegan a tu callback. Para que las llamadas de una herramienta de solo lectura también lleguen a tu callback, añade `destructiveHint: true` a las anotaciones de esa herramienta junto con `readOnlyHint: true`. Como alternativa, establece [`useAutoModeDuringPlan`](https://code.claude.com/docs/es/settings-reference#useautomodeduringplan) en `false`, lo que desactiva el clasificador durante la planificación
1563* **`bypassPermissions`**: cuando la variable de entorno [`CLAUDE_CODE_REMOTE`](https://code.claude.com/docs/es/env-vars#variables) es `true`, como ocurre en una [sesión en la nube](https://code.claude.com/docs/es/claude-code-on-the-web.md), la llamada se aprueba sin tu callback, sean cuales sean las anotaciones de la herramienta. En cualquier otro lugar, la llamada llega a tu callback. Para que llegue a tu callback también en una sesión en la nube, ejecuta la sesión en modo `default` o `acceptEdits` en su lugar
1564
1565Establece `destructiveHint` en `true` explícitamente en los modos `auto` y `plan`. Para las llamadas `always_ask`, Claude Code interpreta un `destructiveHint` sin establecer como `false`, aunque el valor predeterminado indicado en [`ToolAnnotations`](#toolannotations) es `true`.
1566
1442#### `McpClaudeAIProxyServerConfig`1567#### `McpClaudeAIProxyServerConfig`
1443 1568
1444```typescript theme={null}1569```typescript theme={null}
1464| Campo | Tipo | Descripción |1589| Campo | Tipo | Descripción |
1465| :- | :- | :- |1590| :- | :- | :- |
1466| `type` | `'local'` | Debe ser `'local'` (actualmente solo se admiten plugins locales) |1591| `type` | `'local'` | Debe ser `'local'` (actualmente solo se admiten plugins locales) |
1467| `path` | `string` | Ruta absoluta o relativa al directorio del plugin |1592| `path` | `string` | Ruta al directorio del plugin. Una ruta relativa se resuelve respecto de la opción [`cwd`](#options) cuando se inicia la sesión. La ruta debe ser absoluta cuando cargas el plugin a mitad de la sesión con [`addPlugins`](#load-more-plugin-folders-with-addplugins) |
1468| `skipMcpDiscovery` | `boolean` | Cuando es `true`, el SDK carga los skills, hooks, agentes y comandos de este plugin, pero no lee su `.mcp.json` ni los `mcpServers` del manifiesto. Establécelo cuando tu aplicación gestione las conexiones MCP del plugin. |1593| `skipMcpDiscovery` | `boolean` | Cuando es `true`, el SDK carga los skills, hooks, agentes y comandos de este plugin, pero no lee su `.mcp.json` ni los `mcpServers` del manifiesto. Establécelo cuando tu aplicación gestione las conexiones MCP del plugin. |
1469 1594
1470**Ejemplo:**1595**Ejemplo:**
5073};5198};
5074```5199```
5075 5200
5076`source` indica de dónde provino la definición del servidor, con los mismos valores y regla de confianza que el `source` de [`McpServerProvenance`](#mcpserverprovenance). El campo requiere Agent SDK v0.3.274 o posterior y está ausente en versiones anteriores.5201Usa `source` para decidir cuánto confiar en un servidor, y el `_meta` de cada entrada de `tools` para encontrar un recurso de UI que el servidor adjuntó a esa herramienta:
5202
5203* **`source`**: de dónde provino la definición del servidor, con los mismos valores que `source` en [`McpServerProvenance`](#mcpserverprovenance). Basa las decisiones de confianza en `source` en lugar de en `name`, porque solo tu propio servidor en proceso reporta `sdk`, sea cual sea el nombre bajo el que esté registrado cualquier otro servidor. Si no reconoces un valor de `source`, trata ese servidor como tratas cualquier servidor cuyo `source` no sea `sdk`. Requiere Agent SDK v0.3.274 o posterior
5204* **`_meta`**: el objeto `ui` y la cadena `ui/resourceUri` del `_meta` que el servidor declaró para la herramienta. Claude Code retiene todas las demás claves de `_meta`. `ui/resourceUri` es una grafía de nivel superior más antigua de `ui.resourceUri`. Cuando el servidor adjunta un [recurso de UI de MCP Apps](https://code.claude.com/docs/es/mcp.md#reference-mcp-resources) a la herramienta, `ui.resourceUri` o `ui/resourceUri` contiene el URI `ui://` del recurso. Obtén ese URI con [`readMcpResource()`](#query-object) y renderiza el recurso en tu aplicación. Requiere Agent SDK v0.3.280 o posterior
5205
5206Claude Code envía `_meta` solo cuando el array [`capabilities`](#sdksystemmessage) del mensaje `system` con subtipo `init` incluye `mcp_tool_ui_meta_v1`. No tienes que activar `mcp_tool_ui_meta_v1` tú mismo.
5207
5208#### Cuando el `_meta.ui` de una herramienta contiene solo `visibility`
5209
5210Si tu servidor declara `ui.resourceUri` para una herramienta pero el `_meta.ui` que recibe tu aplicación contiene solo `visibility`, el objeto `ui` que envió el servidor no superó una de las comprobaciones de Claude Code. Claude Code comprueba `ui` y `ui/resourceUri` por separado, así que una clave puede llegar a tu aplicación cuando la otra falla. Compara el `_meta` de la respuesta `tools/list` de tu servidor con las comprobaciones de cada clave:
5211
5212* **`ui`**: llega a tu aplicación sin cambios, incluidos los miembros distintos de `resourceUri` y `visibility`, si se superan las tres comprobaciones:
5213
5214 * `resourceUri` está ausente, o es una cadena que comienza con `ui://`
5215 * `visibility` está ausente, o enumera solo `"model"` y `"app"`
5216 * El objeto completo tiene como máximo 4,096 caracteres al serializarse como JSON
5217
5218 Si alguna de las comprobaciones falla, tu aplicación recibe como mucho un `ui` cuyo único miembro es un array `visibility` con las entradas `"model"` y `"app"` que enumeró el servidor.
5219* **`ui/resourceUri`**: llega a tu aplicación si es una cadena que comienza con `ui://` y tiene como máximo 4,096 caracteres. De lo contrario, Claude Code la descarta
5077 5220
5078`_meta` en una entrada de `tools` lleva los miembros de MCP Apps del `_meta` de esa herramienta, para que tu aplicación pueda encontrar el recurso `ui://` que debe renderizar con [`readMcpResource()`](#query-object). Claude Code transmite el objeto `ui` y la cadena plana obsoleta `ui/resourceUri`, y retiene todas las demás claves. Dentro de `ui`, `resourceUri` es una cadena `ui://` y `visibility` un array de `"model"` y `"app"` cuando el servidor los establece, y cualquier otro miembro pasa sin cambios. Claude Code descarta cualquiera de las dos claves cuando el valor está mal formado, y omite `_meta` de una herramienta que no declara ninguna. El campo está presente solo cuando las [`capabilities`](#sdksystemmessage) del mensaje de inicialización incluyen `mcp_tool_ui_meta_v1`, y requiere TypeScript Agent SDK v0.3.280 o posterior.5221Cuando a Claude Code no le queda ningún miembro `ui` ni ninguna cadena `ui/resourceUri` que enviar, la entrada de `tools` no tiene `_meta` en absoluto.
5079 5222
5080### `McpServerStatusConfig`5223### `McpServerStatusConfig`
5081 5224
5310Cuando llamas a `setMcpServers()`, Claude Code aplica estas reglas:5453Cuando llamas a `setMcpServers()`, Claude Code aplica estas reglas:
5311 5454
5312* **Servidores que la llamada no nombra**: fuera de una [sesión en la nube](https://code.claude.com/docs/es/claude-code-on-the-web.md), Claude Code desconecta los servidores que agregó una llamada anterior a `setMcpServers()` y los servidores SDK en proceso, y los enumera en `removed`. Los demás servidores siguen en ejecución y no se enumeran en `removed`, entre ellos los servidores stdio, HTTP y SSE de la opción [`mcpServers`](#options), los servidores de los archivos de configuración y los servidores proporcionados por plugins.5455* **Servidores que la llamada no nombra**: fuera de una [sesión en la nube](https://code.claude.com/docs/es/claude-code-on-the-web.md), Claude Code desconecta los servidores que agregó una llamada anterior a `setMcpServers()` y los servidores SDK en proceso, y los enumera en `removed`. Los demás servidores siguen en ejecución y no se enumeran en `removed`, entre ellos los servidores stdio, HTTP y SSE de la opción [`mcpServers`](#options), los servidores de los archivos de configuración y los servidores proporcionados por plugins.
5313* **Servidores que la llamada nombra**: Claude Code reemplaza un servidor stdio, HTTP o SSE que agregó una llamada anterior a `setMcpServers()` solo cuando su configuración difiere de la que pasaste. Un servidor SDK en proceso ya registrado con ese nombre se queda como está, así que para cambiarlo, déjalo fuera de una llamada y agrégalo en la siguiente.5456* **Servidores stdio, HTTP y SSE que agregó una llamada anterior a `setMcpServers()`**: fuera de una sesión en la nube, un servidor que vuelves a nombrar con una configuración idéntica conserva su conexión y sus herramientas. No aparece ni en `added` ni en `removed`. Si pasas una configuración modificada, Claude Code vuelve a conectar el servidor usando esa configuración y lo enumera en `added`, no en `removed`.
5457* **Servidores stdio, HTTP y SSE que la llamada nombra y que ninguna llamada anterior agregó**: fuera de una sesión en la nube, Claude Code agrega el servidor y lo enumera en `added`, o en `errors` si rechaza el servidor.
5458* **Servidores SDK en proceso que la llamada nombra**: un servidor ya registrado mediante `mcpServers` o una llamada anterior conserva su instancia en ejecución y su tiempo de espera. Si pasas una [lista de políticas `tools`](#mcpsdkserverconfigwithinstance) para él, incluso una vacía, reemplazas sus políticas; de lo contrario, se mantienen. Para ejecutar una nueva instancia fuera de una sesión en la nube, omite el servidor en una llamada y nómbralo en la siguiente.
5314* **Servidores integrados que la CLI inició al arrancar**: si la llamada nombra uno, Claude Code descarta esa entrada y la reporta en `errors`.5459* **Servidores integrados que la CLI inició al arrancar**: si la llamada nombra uno, Claude Code descarta esa entrada y la reporta en `errors`.
5315* **Servidores stdio, HTTP o SSE que comparten nombre con uno de un alcance de instalación de MCP como `.mcp.json`**: con ese nombre, la sesión usa las herramientas de tu servidor en lugar de las del [servidor del alcance de instalación](https://code.claude.com/docs/es/mcp.md#mcp-installation-scopes). Antes de Claude Code v2.1.305, Claude Code podía desconectar tu servidor y conectar el servidor del alcance de instalación cuando tu aplicación [recargaba plugins](#query-object).5460* **Servidores stdio, HTTP o SSE que comparten nombre con uno de un alcance de instalación de MCP como `.mcp.json`**: con ese nombre, la sesión usa las herramientas de tu servidor en lugar de las del [servidor del alcance de instalación](https://code.claude.com/docs/es/mcp.md#mcp-installation-scopes). Antes de Claude Code v2.1.305, Claude Code podía desconectar tu servidor y conectar el servidor del alcance de instalación cuando tu aplicación [recargaba plugins](#query-object).
5316 5461
5797 5942
5798Las definiciones de tipos publicadas del SDK declaran `SDKConversationResetMessage` en Claude Code v2.1.203 y posterior. Antes de v2.1.203, `SDKMessage` hacía referencia al tipo sin declararlo, por lo que el estrechamiento con `type === "conversation_reset"` no pasaba la verificación de tipos cuando `skipLibCheck` estaba deshabilitado.5943Las definiciones de tipos publicadas del SDK declaran `SDKConversationResetMessage` en Claude Code v2.1.203 y posterior. Antes de v2.1.203, `SDKMessage` hacía referencia al tipo sin declararlo, por lo que el estrechamiento con `type === "conversation_reset"` no pasaba la verificación de tipos cuando `skipLibCheck` estaba deshabilitado.
5799 5944
5945### `BUILTIN_TOOL_NAMES` y `LEGACY_TOOL_NAME_ALIASES`
5946
5947Usa estas dos constantes para comprobar los nombres de herramientas que introducen los usuarios de tu aplicación. Ambas escriben cada nombre tal como lo escribes en las reglas de permisos, los matchers de hooks y las opciones `tools` y `disallowedTools`. Impórtalas desde `@anthropic-ai/claude-agent-sdk` o desde `@anthropic-ai/claude-agent-sdk/core`. Requieren Agent SDK v0.3.301 o posterior y están en fase alfa.
5948
5949Las declaraciones de tipos del SDK dan a `BUILTIN_TOOL_NAMES` un tipo de tupla de solo lectura y a `LEGACY_TOOL_NAME_ALIASES` un tipo de registro de cadena a cadena:
5950
5951```typescript theme={null}
5952const BUILTIN_TOOL_NAMES: readonly ["Agent", /* ...más nombres... */ "Write"];
5953const LEGACY_TOOL_NAME_ALIASES: Readonly<Record<string, string>>;
5954```
5955
5956* **`BUILTIN_TOOL_NAMES`**: nombres de las herramientas integradas de Claude Code en orden alfabético, como `Agent`, `Bash` y `Read`. Los nombres de herramientas MCP no se incluyen. Como el tipo es una tupla de literales de cadena, `(typeof BUILTIN_TOOL_NAMES)[number]` te da un tipo unión de los nombres
5957* **`LEGACY_TOOL_NAME_ALIASES`**: nombres de herramientas anteriores que las reglas de permisos, los matchers de hooks y las opciones `tools` y `disallowedTools` todavía aceptan. Cada clave es un nombre anterior y su valor es el actual: por ejemplo, `Task` se asigna a `Agent`, y `KillShell` y `KillBash` se asignan a `TaskStop`
5958
5959Puedes confirmar un nombre con cualquiera de dos pruebas: `BUILTIN_TOOL_NAMES` lo incluye, u `Object.hasOwn(LEGACY_TOOL_NAME_ALIASES, name)` devuelve `true`. Un nombre que no supera ninguna de las dos puede seguir siendo válido, porque `BUILTIN_TOOL_NAMES` deja fuera las herramientas MCP y algunas herramientas integradas. Si creas una lista de denegación a partir de `BUILTIN_TOOL_NAMES`, Claude todavía puede usar las herramientas que la constante deja fuera. Para denegar todas las herramientas, establece [`disallowedTools: ["*"]`](https://code.claude.com/docs/es/agent-sdk/permissions#allow-and-deny-rules) en su lugar.
5960
5961Encontrar un nombre en `BUILTIN_TOOL_NAMES` no te indica que la sesión tenga esa herramienta: `TodoWrite` aparece en la lista aunque está [deshabilitada de forma predeterminada](https://code.claude.com/docs/es/tools-reference.md). Para ver qué herramientas tiene una sesión, lee el array `tools` de su [`SDKSystemMessage`](#sdksystemmessage). Ese array incluye herramientas MCP y enumera la herramienta Agent como `Task`, así que pasa cada nombre por `LEGACY_TOOL_NAME_ALIASES` antes de compararlo con `BUILTIN_TOOL_NAMES`.
5962
5800### `AbortError`5963### `AbortError`
5801 5964
5802Clase de error personalizada para operaciones de aborto.5965Clase de error personalizada para operaciones de aborto.
