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

# Build an agent with MCP

> Connect an AI assistant or your own agent to Brelio's MCP server, with prompts to try and the rules the server follows.

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](https://docs.brelio.com/en/quickstart/mcp.md). 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](https://docs.brelio.com/en/changelog.md#known-limitations). Patient prompts also need the clinic's patient [data area](https://docs.brelio.com/en/concepts/data-areas.md) on.

A longer prompt that sets the agent up for front-desk work:

```text System prompt theme={null}
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](https://docs.brelio.com/en/guides/book-appointment.md) 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](https://docs.brelio.com/en/mcp/tools.md).

## Call it from your own code

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

Without a token the server answers `401` with a `WWW-Authenticate` header that points to its [OAuth metadata](https://docs.brelio.com/en/authentication.md#mcp-oauth); MCP SDKs follow it for you.

With the official TypeScript SDK:

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

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:

```text Prompt theme={null}
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.
```


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