Crea un agente con MCP

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. 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. Los de pacientes necesitan además el área de datos de pacientes activada en la clínica. Un prompt más largo que prepara al agente para trabajar en recepción:

Prompt de sistema

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 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.

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:

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}}}'

Respuesta

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; los SDK de MCP la siguen por ti. Con el SDK oficial de TypeScript:

agent.ts

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:

Prompt

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.

Empezar

Conceptos

Guías

Referencia MCP

Referencia

Crea un agente con MCP

Conecta

Prompts para probar

Cómo se comporta el servidor

Llámalo desde tu código

Agentes que llaman a REST

​Conecta

​Prompts para probar

​Cómo se comporta el servidor

​Llámalo desde tu código

​Agentes que llaman a REST

Conecta

Prompts para probar

Cómo se comporta el servidor

Llámalo desde tu código

Agentes que llaman a REST