---
title: "MCP"
description: "Conecta un cliente MCP a Arbol. La URL del servidor, el inicio de sesión, las herramientas que ves y cómo se mantienen cortas las respuestas."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.getarbol.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/developers/authentication/) y [Conceptos](/developers/concepts/).

## 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:

### Iniciar sesión

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

Un cliente que admite la autorización de MCP te pide iniciar sesión la primera vez que se conecta. Consulta [Inicio de sesión](#inicio-de-sesión).

### API key

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

Usa una API key para un agente desatendido, o con un cliente que no puede iniciar sesión. Dale a la key solo los scopes que necesita el agente, y deja el archivo fuera del control de versiones.

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](/developers/authentication/#descubrimiento-de-oauth) y los scopes que exigen sus herramientas:

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

1. El cliente lee los metadatos, que nombran el servidor de autorización de Arbol, `https://auth.getarbol.com/`.
2. Ahí inicia tu sesión para el recurso `https://api.getarbol.com`, con una de tus organizaciones seleccionada.
3. Se vuelve a conectar con el token de acceso.

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.

> **Si el inicio de sesión falla**
>
> El servidor de autorización de Arbol compara el recurso exactamente como lo dan los metadatos, `https://api.getarbol.com`, sin barra final, y todo token debe llevar una organización. Si tu cliente no puede completar el inicio de sesión, conéctate con una API key.

## 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](/developers/concepts/retries/).

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:

| Herramienta | Qué hace |
| --- | --- |
| `search_tools` | Encuentra las herramientas que puedes llamar, por lo que hacen. |
| `run_read_tool` | Ejecuta una herramienta que solo lee. |
| `run_write_tool` | Ejecuta una herramienta que crea o cambia algo. |
| `run_delete_tool` | Ejecuta una herramienta que elimina algo. |

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`:

```json
{
  "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:

```json
{
  "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`](/api/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](/developers/concepts/responses-and-errors/). 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](/developers/concepts/responses-and-errors/#respuestas-en-texto-para-agentes-de-ia) y, para ADRES, Sisbén y Policía Colombia, [Registros colombianos](/developers/integrations/#registros-colombianos).

Source: https://docs.getarbol.com/developers/mcp/index.mdx