Build an agent with MCP

Brelio’s MCP server turns the clinic’s data into tools an AI model can call. This guide shows prompts that work well, how the server behaves, and how to call it from your own code.

Connect

Follow Connect your AI assistant. For your own agent, any MCP client that supports Streamable HTTP and OAuth works: point it at https://api.brelio.app/mcp.

Prompts to try

Copy them into your assistant with the Brelio connector on. They are in Spanish, as a receptionist would ask; the assistant answers in the language you write in.

Prompt	Tools it uses
¿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` with `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`

The last three need the agenda and patient tools; see known limitations. Patient prompts also need the clinic’s patient data area on. A longer prompt that sets the agent up for front-desk work:

System prompt

You help the front desk of a clinic that uses Brelio. Use only the Brelio tools for
facts about the clinic; never guess names, times or prices. Times from Brelio are UTC:
convert them to the clinic's time zone (Europe/Madrid) before showing them. Before
proposing an appointment, find free slots with brelio_search_availability. If a tool
answers with an error, read its `code` and `hint` and explain what the person can do.
Never include clinical information in anything you write to Brelio.

How the server behaves

It acts as the person who connected it, in one clinic, with that person’s permissions read on every call. Tools the person cannot use are not listed.
Read tools only, in this version. Booking, rescheduling, cancelling and patient changes are REST for now. When write tools arrive, destructive ones (cancel, archive, delete) will ask the person to confirm before acting.
Every tool has a JSON Schema for its input and output, returns structuredContent, and carries readOnlyHint and destructiveHint annotations.
Lists are paginated: pass next_cursor back as cursor while has_more is true.
Errors are the same problem objects as REST, returned as a tool result with isError: true. Follow the hint rather than retrying blindly.
Patient-data acceptance: if the connection was not accepted for patient data, a patient tool returns PATIENT_DATA_CONSENT_REQUIRED. Clients that support URL elicitation open Brelio’s acceptance page; others get the link in params.consent_url and the hint.
Secrets never pass through MCP. Operations that reveal a one-time secret (a webhook’s signing secret) are not offered, and refuse with PLATFORM_REVEAL_FORBIDDEN.

The full list, with arguments and examples, is in MCP tools.

Call it from your own code

The server is stateless Streamable HTTP. With an access token for 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}}}'

Response

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}

Without a token the server answers 401 with a WWW-Authenticate header that points to its OAuth metadata; MCP SDKs follow it for you. With the official TypeScript SDK:

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)

In production, let the SDK’s OAuth support (authProvider) obtain and refresh the token instead of passing one by hand.

Agents that call REST

An agent that writes code against the API, rather than using MCP tools, can start from the OpenAPI document at https://api.brelio.app/v1/openapi.json. Every operation there carries x-brelio-permission, x-brelio-data-class, x-brelio-risk and x-brelio-examples. This prompt sets one up:

Prompt

I want to integrate with the Brelio API.
- OpenAPI: https://api.brelio.app/v1/openapi.json
- Base URL: https://api.brelio.app/v1
- Auth: Authorization: Bearer <BRELIO_API_KEY>, read from the environment, never hard-coded.
- Every POST/PATCH needs an Idempotency-Key; updates need expectedVersion from the last read.
Smoke test first: without a key the API must answer 401; with the key, GET /v1/services
must list the clinic's services. Use only operations in the OpenAPI document.

Get started

Concepts

Guides

MCP reference

Reference

Build an agent with MCP

Connect

Prompts to try

How the server behaves

Call it from your own code

Agents that call REST

​Connect

​Prompts to try

​How the server behaves

​Call it from your own code

​Agents that call REST

Connect

Prompts to try

How the server behaves

Call it from your own code

Agents that call REST