MCP

El servidor MCP de Arbol ofrece las operaciones de la API como herramientas para clientes de IA. Corre en la propia URL de la API, https://api.getarbol.com, sobre Streamable HTTP. Su dirección anterior, https://mcp.getarbol.com, redirige ahí.

Una llamada a una herramienta es la solicitud REST que describe su operación, enviada con tu credencial. Los mismos permisos (scopes) la deciden y vuelven los mismos errores, así que aplica todo lo que dicen Autenticación y Conceptos.

Agregar el servidor a tu cliente

Agrega https://api.getarbol.com a tu cliente como servidor remoto. Cada cliente tiene su propio archivo de configuración y sus propios nombres de campo, así que revisa su documentación. Una forma común:

{
  "mcpServers": {
    "arbol": {
      "url": "https://api.getarbol.com"
    }
  }
}

{
  "mcpServers": {
    "arbol": {
      "url": "https://api.getarbol.com",
      "headers": {
        "Authorization": "Bearer arb_live_…"
      }
    }
  }
}

Un GET https://api.getarbol.com/ simple, como el de un navegador, responde con el índice de la API en lugar de MCP. Los clientes envían sus solicitudes MCP a la misma URL con POST.

Inicio de sesión

Sin una credencial válida, el servidor responde 401 con un desafío que nombra los metadatos de recurso protegido y los scopes que exigen sus herramientas:

WWW-Authenticate: Bearer resource_metadata="https://api.getarbol.com/.well-known/oauth-protected-resource", scope="account:api-keys:read account:api-keys:write …"

El token actúa en la organización que seleccionaste. Tiene los scopes que pidió el cliente, hasta donde tus roles los otorgan, así que un cliente que no pide ningún scope no obtiene ninguna herramienta.

Las herramientas que ves

El servidor lista solo las herramientas que tu credencial puede usar: la operación debe aceptar tu tipo de quien llama (una persona o una máquina), tu credencial debe tener uno de sus scopes, y las restricciones de una API key deben permitirla. Llamar a una herramienta igual pasa por las mismas verificaciones que REST.

Cada herramienta lleva el nombre de su operación: account.organization.get es la herramienta account_organization_get. Sus anotaciones vienen del efecto (Effect) de la operación: readOnlyHint para una lectura, destructiveHint para una eliminación, e idempotentHint cuando es idempotente. Consulta Reintentos.

No todas las operaciones son herramientas. La página de cada operación en la referencia de la API nombra su herramienta MCP, o dice que no se ofrece en MCP; esas son solo por REST.

Cuando puedes usar más de 40 herramientas

A un modelo le cuesta elegir en una lista larga, así que cuando tu credencial puede usar más de 40 herramientas, el servidor lista estas en su lugar:

Un ejecutor aparece solo cuando tienes herramientas con su efecto. Como cada efecto tiene su propio ejecutor, la aprobación que un cliente da a run_read_tool nunca cubre una escritura ni una eliminación.

search_tools recibe una query en inglés, como "list appointments", y opcionalmente un service y un limit (10 por defecto, hasta 50). Cada coincidencia vuelve resumida: su nombre, su efecto, su ejecutor, lo que hace, su entrada como firma y, para una lectura, los campos que devuelve. Antes de llamar a una herramienta cuya entrada no conoces del todo, sobre todo si es una escritura, pídela por names, hasta cinco a la vez, para obtener su esquema de entrada completo.

Luego llama al ejecutor con el nombre de la herramienta y su entrada. Como parámetros de una solicitud MCP tools/call:

{
  "name": "run_read_tool",
  "arguments": {
    "name": "account_organization_get",
    "arguments": {}
  }
}

Respuestas cortas

Un modelo lee cada respuesta completa, en cada paso, así que las herramientas de lectura pueden responder menos de lo que responde REST:

• fields. Toda herramienta de lectura recibe fields además de su propia entrada: hasta 50 nombres de campo. Cada registro vuelve entonces solo con esos campos, y siempre con su id. El valor nunca llega al servicio.
• omittedFields. Una lista de más de 16 KB, pedida sin fields, deja fuera los campos más grandes de sus elementos, los de más de 512 bytes por elemento en promedio, y los nombra en omittedFields. Pídelos con fields, o lee un solo registro.

Por ejemplo, una llamada a account_api_keys_list que pide solo el nombre y los scopes de cada key:

{
  "name": "account_api_keys_list",
  "arguments": { "limit": 100, "fields": ["name", "scopes"] }
}

Las respuestas REST nunca se recortan de esta forma. Una operación, nueva-eps.affiliations.lookup, define su propio fields, que funciona como lo describe su referencia.

Errores

Una llamada rechazada vuelve como un resultado de herramienta con isError: true. Su texto es el mismo objeto de error que responde REST, con code, message, retryable y data: consulta Respuestas y errores. Una herramienta llamada con el ejecutor equivocado se rechaza con INVALID_INPUT, y el data.runner del error nombra el correcto.

Integraciones

Las operaciones de las integraciones también son herramientas, como sura_appointments_create o adres_affiliations_lookup, con la misma entrada que su operación REST y las mismas comprobaciones: la integración activa en tu organización y las restricciones de tu credencial. Algunas reciben agentMode para responder un texto breve en español: consulta Respuestas en texto para agentes de IA y, para ADRES, Sisbén y Policía Colombia, Registros colombianos.