Herramientas

El servidor MCP no tiene una herramienta por función. Con tres herramientas generales, un cliente de IA llega a todas las operaciones de la API REST (en inglés) salvo la subida de archivos, siempre en tu nombre y con tus permisos. Una cuarta herramienta devuelve tu propio perfil. Cuando la API incorpora una función nueva, los clientes pueden usarla de inmediato.

Tres herramientas solo leen. Write to the API está marcada como herramienta que puede cambiar datos, así que, por defecto, los clientes te piden que la apruebes. La mayoría de los clientes te dejan permitirla para una conversación o de forma permanente. Permisos y seguridad explica qué puede hacer un cliente.

Cómo usa un cliente las herramientas

Cada cliente también recibe del servidor un breve conjunto de instrucciones. Describen tres pasos: encontrar la operación con search_api, leer lo que acepta y después llamarla con api_read o api_write. También le indican al cliente que:

• las rutas de los elementos de trabajo aceptan claves como ACM-12
• los filtros de usuario aceptan me
• eliminar necesita confirm: true, que solo se envía después de que hayas dado tu conformidad, y solo funciona si tu organización lo permite
• el texto se añade a un documento de Drive con mode: append, porque sin él se sustituye el documento entero

search_api

Busca operaciones de la API y las describe. Solo devuelve la documentación de la propia API, nunca datos de tu organización.

• Con query, devuelve como máximo 12 coincidencias en forma de {id, method, path, summary}, más un hint con el siguiente paso.
• Con operation_id, describe esa operación: su descripción, el permiso que necesita, los parámetros de ruta, los parámetros de consulta, los filtros, las ordenaciones, las relaciones que se pueden incluir (include), los campos del cuerpo, la función a la que pertenece y uno o dos ejemplos. El id funciona con o sin el prefijo api.v2..
• Sin ninguna de las dos entradas, enumera todos los ids de operación, agrupados por área.

Se omiten las operaciones que tu organización no puede usar: las de las áreas que tu organización no usa, las eliminaciones mientras Permitir acciones destructivas está desactivado y la subida de archivos.

api_read

Envía un GET a cualquier operación de la API.

Rutas y consulta

• Una ruta vacía enumera los recursos que ofrece la API.
• La ruta puede empezar por /api/v2; el prefijo se ignora.
• La ruta completa tiene como máximo 256 caracteres. Sus segmentos solo usan letras, dígitos, - y _, y todos los marcadores deben estar rellenados.
• Las rutas de los elementos de trabajo aceptan claves, como work-items/ACM-12. Los filtros de usuario aceptan me.
• Los objetos de consulta se anidan como máximo tres niveles, como filter[due_date][gte], con un máximo de 60 parámetros en total.
• Los valores nulos se omiten. Las listas se convierten en valores separados por comas.

Listas y paginación

Las listas llegan en páginas de 10 en la vista resumida, salvo que la llamada pida otra cosa. Para obtener la página siguiente, pasa como cursor el meta.page.next_cursor de la respuesta anterior. Cuando next_cursor es null, no hay más páginas.

Algunas listas también aceptan un número de página. Su meta.page siempre tiene current_page y last_page, que son null salvo que la llamada envíe page. Una llamada que envía page siempre recibe next_cursor: null. La última página es aquella en la que current_page llega a last_page.

api_write

Envía un POST, PATCH o DELETE a cualquier operación de la API.

Las reglas de ruta y consulta de api_read también se aplican aquí. El cuerpo se comprueba exactamente igual que en la API REST: un campo que la operación no acepta se rechaza por su nombre, nunca se ignora.

Eliminar necesita dos cosas: Permitir acciones destructivas debe estar activado para tu organización, y la llamada debe llevar confirm: true. Si falta cualquiera de las dos, no se elimina nada. Qué cuenta como eliminar enumera las operaciones afectadas. En DELETE /projects/{project}, la consulta {"force": true} elimina el proyecto de forma permanente, en lugar de hacer una eliminación que se puede deshacer.

Sustituir el texto completo de un documento de Drive también necesita confirm: true, porque descarta el formato y todo lo que otros hayan escrito desde que el cliente lo leyó. Añadir texto con {"mode": "append"} en el cuerpo no necesita confirmación.

api_write rechaza estas llamadas antes de que se ejecute nada:

Ninguno de los dos primeros lee el registro antes de rechazar la llamada, así que un rechazo nunca revela si el registro existe.

Las escrituras mediante MCP no están protegidas contra duplicados. La cabecera Idempotency-Key ni se necesita ni se usa, así que un cliente que no sabe con seguridad si una escritura se completó debe leer antes de volver a intentarlo.

Si el inicio de sesión de una aplicación también pidió permisos de la API REST, mediante MCP queda limitada igualmente a esos permisos. Los permisos de un inicio de sesión nunca incluyen eliminar, así que esa aplicación no puede eliminar mediante MCP.

get-current-user-tool

Devuelve tu propio perfil. No recibe ninguna entrada.

{
  "id": 34,
  "name": "Jamie Doe",
  "email": "jamie@acme.example",
  "email_verified_at": "2026-02-03T09:15:00+00:00",
  "timezone": "Europe/Amsterdam",
  "locale": "en",
  "job_title": "Project manager",
  "date_employed": "2025-09-01",
  "roles": ["Project manager"],
  "created_at": "2025-08-28T14:02:11+00:00"
}

Las marcas de tiempo incluyen la diferencia con la hora UTC. date_employed es una fecha (YYYY-MM-DD). Los campos sin valor son null.

Respuestas

Una respuesta correcta es el propio cuerpo de respuesta de la API, con dos cambios:

• Primero va una clave status, con el estado HTTP con el que respondió la API, como 200 o 201.
• Se quitan todos los mapas links. Un cliente continúa una lista con meta.page.next_cursor y llama a otros registros por su ruta.

Una eliminación responde sin cuerpo, así que la herramienta devuelve {"status": 204}.

Una respuesta puede tener unos 30.000 caracteres. El límite cuenta bytes, así que en un texto con tildes o emojis caben algunos menos. Una respuesta más larga se acorta, pero nunca en silencio: meta.mcp_truncated indica qué se ha cortado. Cuando se omiten filas de una lista, next_cursor se vacía, porque al seguirlo esas filas se saltarían. El hint explica cómo seguir paginando sin huecos. Este es el objeto meta de una lista acortada:

{
  "page": {
    "per_page": 10,
    "next_cursor": null,
    "prev_cursor": null,
    "total": null
  },
  "mcp_truncated": {
    "reason": "response_budget",
    "returned": 6,
    "omitted": 4,
    "hint": "Only the first 6 of 10 rows fit. Repeat this request with per_page=6 (and the same cursor, if any) to page through without gaps."
  }
}

Cuando el problema es un único texto largo, mcp_truncated enumera en su lugar los campos acortados, cada uno con su pointer, los caracteres que se han conservado (kept) y la longitud original (length).

Errores

Una llamada rechazada vuelve como error de herramienta con el mismo documento de error (en inglés) que devuelve la API REST, con el mismo estado y el mismo tipo. Pedir algo que no tienes permiso para ver devuelve 404, igual que mediante HTTP.

{
  "type": "https://developers.plnnrly.com/api/v2/problems/forbidden-by-policy",
  "title": "Forbidden by policy",
  "status": 403,
  "detail": "This organisation does not allow AI clients to delete data. An administrator can turn on Allow destructive actions under Settings › Administration › MCP & API.",
  "instance": "/api/v2/work-items/ACM-12",
  "request_id": "01M4WVYY50K7T2B9QH3D6N8RXP"
}

Una ruta o una consulta que las herramientas no pueden usar responde malformed-request. Su errors[].code es invalid (una ruta o un valor no permitidos), too_many (más de 60 parámetros de consulta) o too_deep (anidado más de tres niveles).

Límites

• Cada usuario puede enviar 60 peticiones MCP por minuto. Cuenta cada petición que el cliente envía al servidor, incluidas las que establecen la conexión y enumeran las herramientas, no solo las llamadas a herramientas. Un cliente que supera el límite recibe 429.
• Los límites de peticiones de la propia API REST y sus unidades de coste no se aplican a las llamadas mediante MCP.
• Una respuesta tiene unos 30.000 caracteres como máximo.
• El cliente renueva su inicio de sesión cada hora. Un cliente que no se usa durante 30 días tiene que volver a iniciar sesión.

Límites de un vistazo (en inglés) enumera todos los límites de la API REST.

Lo que MCP no puede hacer

• Subir archivos. Añadir un adjunto o un archivo de Drive necesita una subida de bytes que los clientes MCP no pueden hacer. Usa la API REST con un token de API; consulta Archivos: subida y descarga (en inglés).
• Eliminar mientras el interruptor está desactivado. Las eliminaciones solo funcionan mientras tu organización permite acciones destructivas.

Páginas relacionadas

• Qué puedes pedir
• Permisos y seguridad
• Solución de problemas
• Errores y reintentos (en inglés)