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

# Crea un agente con MCP

> Conecta un asistente de IA o tu propio agente al servidor MCP de Brelio, con prompts para probar y las reglas que sigue el servidor.

El servidor MCP de Brelio convierte los datos de la clínica en herramientas que un modelo de IA puede llamar. Esta guía muestra prompts que funcionan bien, cómo se comporta el servidor y cómo llamarlo desde tu propio código.

## Conecta

Sigue [Conecta tu asistente de IA](https://docs.brelio.com/es/quickstart/mcp.md). Para tu propio agente sirve cualquier cliente MCP que admita Streamable HTTP y OAuth: apúntalo a `https://api.brelio.app/mcp`.

## Prompts para probar

Cópialos en tu asistente con el conector de Brelio activado. El asistente responde en el idioma en que escribes.

| Prompt | Herramientas que usa |
| - | - |
| ¿Qué servicios ofrecemos y cuánto dura cada uno? | `brelio_list_services` |
| ¿Qué profesionales trabajan en la clínica y cuáles están activos? | `brelio_list_professionals` |
| ¿En qué centros trabajamos? ¿Cuál es el principal? | `brelio_list_centers` |
| ¿Hay algún servicio de fisioterapia? ¿Cuánto cuesta? | `brelio_list_services` con `search` |
| ¿Qué datos de pacientes pueden usar ahora mismo los asistentes? | `brelio_list_platform_policy` |
| ¿Quién ha cambiado los permisos de datos de la clínica últimamente? | `brelio_list_platform_policy_decisions` |
| ¿Qué webhooks tenemos y alguno está fallando? | `brelio_list_webhooks`, `brelio_get_webhooks` |
| ¿Cuántas citas hay mañana y con quién? | `brelio_list_agenda` |
| ¿Qué huecos libres tiene Laia el jueves por la mañana para fisioterapia? | `brelio_list_professionals`, `brelio_list_services`, `brelio_search_availability` |
| Busca a la paciente Ana Pérez y dime su teléfono. | `brelio_list_patients` |

Los tres últimos necesitan las herramientas de agenda y pacientes; consulta las [limitaciones conocidas](https://docs.brelio.com/es/changelog.md#limitaciones-conocidas). Los de pacientes necesitan además el [área de datos](https://docs.brelio.com/es/concepts/data-areas.md) de pacientes activada en la clínica.

Un prompt más largo que prepara al agente para trabajar en recepción:

```text Prompt de sistema theme={null}
Ayudas a la recepción de una clínica que usa Brelio. Usa solo las herramientas de Brelio
para los datos de la clínica; nunca inventes nombres, horas ni precios. Las horas de Brelio
están en UTC: pásalas a la zona horaria de la clínica (Europe/Madrid) antes de mostrarlas.
Antes de proponer una cita, busca huecos libres con brelio_search_availability. Si una
herramienta responde con un error, lee su `code` y su `hint` y explica qué puede hacer la
persona. Nunca escribas información clínica en nada que envíes a Brelio.
```

## Cómo se comporta el servidor

* **Actúa como la persona que lo conectó**, en una clínica, con los permisos de esa persona leídos en cada llamada. Las herramientas que la persona no puede usar no aparecen.
* **Solo herramientas de lectura, en esta versión.** Reservar, reprogramar, cancelar y cambiar pacientes es por [REST](https://docs.brelio.com/es/guides/book-appointment.md) de momento. Cuando lleguen las herramientas de escritura, las destructivas (cancelar, archivar, eliminar) pedirán confirmación a la persona antes de actuar.
* **Cada herramienta tiene un JSON Schema de entrada y de salida**, devuelve `structuredContent` y lleva las anotaciones `readOnlyHint` y `destructiveHint`.
* **Las listas están paginadas:** devuelve `next_cursor` como `cursor` mientras `has_more` sea true.
* **Los errores son los mismos objetos problem que en REST**, devueltos como resultado de la herramienta con `isError: true`. Sigue el `hint` en lugar de reintentar a ciegas.
* **Aceptación de datos de pacientes:** si la conexión no está aceptada para datos de pacientes, una herramienta de pacientes devuelve `PATIENT_DATA_CONSENT_REQUIRED`. Los clientes que admiten elicitation por URL abren la página de aceptación de Brelio; los demás reciben el enlace en `params.consent_url` y en el `hint`.
* **Los secretos nunca pasan por MCP.** Las operaciones que revelan un secreto de un solo uso (el secreto de firma de un webhook) no se ofrecen, y se rechazan con `PLATFORM_REVEAL_FORBIDDEN`.

La lista completa, con argumentos y ejemplos, está en [Herramientas MCP](https://docs.brelio.com/es/mcp/tools.md).

## Llámalo desde tu código

El servidor es Streamable HTTP sin estado. Con un token de acceso para `resource=https://api.brelio.app/mcp`:

```bash theme={null}
curl -s https://api.brelio.app/mcp \
  -H "Authorization: Bearer $MCP_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"brelio_list_services","arguments":{"limit":5}}}'
```

```text Respuesta theme={null}
event: message
data: {"result":{"structuredContent":{"data":[{"id":"c3c8e275-…","name":"Fisioterapia","defaultDuration":45,…}],"next_cursor":null,"has_more":false},"content":[{"type":"text","text":"{…}"}]},"jsonrpc":"2.0","id":1}
```

Sin token el servidor responde `401` con una cabecera `WWW-Authenticate` que apunta a sus [metadatos OAuth](https://docs.brelio.com/es/authentication.md#oauth-de-mcp); los SDK de MCP la siguen por ti.

Con el SDK oficial de TypeScript:

```typescript agent.ts theme={null}
import { Client } from '@modelcontextprotocol/sdk/client/index.js'
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'

const transport = new StreamableHTTPClientTransport(new URL('https://api.brelio.app/mcp'), {
  requestInit: { headers: { Authorization: `Bearer ${process.env.MCP_ACCESS_TOKEN}` } },
})
const client = new Client({ name: 'my-clinic-agent', version: '1.0.0' })
await client.connect(transport)

const { tools } = await client.listTools()
console.log(tools.map((tool) => tool.name))

const services = await client.callTool({ name: 'brelio_list_services', arguments: { limit: 5 } })
console.log(services.structuredContent)
```

En producción, deja que el soporte OAuth del SDK (`authProvider`) obtenga y renueve el token en lugar de pasarlo a mano.

## Agentes que llaman a REST

Un agente que escribe código contra la API, en lugar de usar herramientas MCP, puede partir del documento OpenAPI en `https://api.brelio.app/v1/openapi.json`. Cada operación lleva `x-brelio-permission`, `x-brelio-data-class`, `x-brelio-risk` y `x-brelio-examples`. Este prompt lo prepara:

```text Prompt theme={null}
Quiero integrarme con la API de Brelio.
- OpenAPI: https://api.brelio.app/v1/openapi.json
- URL base: https://api.brelio.app/v1
- Autenticación: Authorization: Bearer <BRELIO_API_KEY>, leída del entorno, nunca escrita en el código.
- Cada POST/PATCH necesita una Idempotency-Key; las actualizaciones necesitan la expectedVersion de la última lectura.
Antes de nada, haz un smoke test: sin clave la API debe responder 401; con la clave,
GET /v1/services debe listar los servicios de la clínica. Usa solo operaciones del documento OpenAPI.
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.