MCP Integration - Mirobody

The health-data tools used by the bundled agent are also served at /mcp, over the Model Context Protocol. An MCP client such as Claude Desktop, Cursor or an agent loop of your own calls those tools over the same personal record. A separate stdio server provides terminology tools without a personal record.

Endpoints

Route	Identifies the caller by	Use
`POST /mcp`	`Authorization: Bearer <access token>`	A client that can send a header
`POST /mcp/<secret>`	The secret in the path	A personal URL, for a client that cannot send a header
`GET /personal/mcp`	`Authorization: Bearer <access token>`	Lists the links the caller made and the ones reading the caller’s record
`POST /personal/mcp`	`Authorization: Bearer <access token>`	Replaces the caller’s personal URL (or, with `user_id` in the body, a family member’s link to that person)
`DELETE /personal/mcp`	`Authorization: Bearer <access token>`	Revokes the link the caller made for that person (their own, or with `user_id` in the body, a family member’s)
`DELETE /personal/mcp/<id>`	`Authorization: Bearer <access token>`	Revokes one link by id, made by the caller or reading the caller’s record

All of these sit under HTTP_URI_PREFIX when one is set. On the Docker stack the server listens on port .

Personal MCP URL

A personal URL carries its own credential, so a desktop client needs no sign-in flow. The web client shows it under Settings → MCP; your own client mints it with the access token it already holds:

# sign in with a demo account (a real deployment signs in the way its users do)
TOKEN=$(curl -s -X POST http://localhost:18060/email/verify \
  -H 'Content-Type: application/json' \
  -d '{"email": "you@mirobody.ai", "code": "111111"}' | jq -r .data.access_token)

curl -s -X POST http://localhost:18060/personal/mcp -H "Authorization: Bearer $TOKEN"

{ "code": 0, "msg": "ok", "data": { "url": "http://localhost:18060/mcp/<secret>" } }

Minting again replaces the URL: it revokes any live link for the same caller and subject and issues a new secret, valid for MCP_URL_TTL_DAYS days from that moment ( by default), never extended by use. GET /personal/mcp lists every live link the caller can see: the ones they made (for themselves or, with a care-circle read grant, for someone else) and the ones a family member made that read the caller’s own record. DELETE /personal/mcp/<id> revokes one link by its id, whether the caller made it or it reads the caller’s record; a link nobody may act on answers 404, the same as one that does not exist. Sharing stopping, a circle membership ending, or the creator’s account being taken back over all end the link the next time it is used, and unsharing or removal also revoke it outright so sharing again later does not silently restore it.

Every personal MCP link made before 1.5.3 stopped working: the old store kept a link by subject alone, with no creator to check, so nobody’s old link can be told apart from anyone else’s. Make a new one in Settings.

The secret is the whole credential: anyone holding the URL can read that person’s health record. It ends up in client configuration files and screenshots, so treat it like a password, revoke it when a device is lost, and serve it only over HTTPS once the deployment is reachable from a network.

The URL starts with the origin the request arrived on. Behind a reverse proxy, that origin is only correct when the server trusts the proxy’s forwarded headers; see Deploy on a Server.

Tools an account sees

The endpoint serves these tools: tools/list is filtered per account: a data tool is hidden from an account that holds none of that data, so a client never sees a tool whose only answer would be “no data”. The filtered tools are . What each tool accepts and returns is in Health-Data Tools, and tools you add yourself are served the same way; see Adding Tools. The chat-only tools (the file tools, eval and ask_user) are not served over MCP.

Connect a client

Replace the URL below with your personal URL.

Cursor
Claude Code
Claude Desktop

Cursor connects to a remote server directly. Add it to ~/.cursor/mcp.json, or to .cursor/mcp.json in a project:

{
  "mcpServers": {
    "mirobody": { "url": "http://localhost:18060/mcp/<secret>" }
  }
}

claude mcp add --transport http mirobody http://localhost:18060/mcp/<secret>

Claude Desktop adds remote servers as custom connectors, which need an HTTPS URL it can reach. For an engine on your own machine, bridge the URL over stdio instead, in claude_desktop_config.json:

{
  "mcpServers": {
    "mirobody": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:18060/mcp/<secret>"]
    }
  }
}

An agent loop of your own calls the endpoint with any MCP client library. The server speaks the current stateless protocol revision and negotiates down for clients that still use the initialize handshake.

Local terminology over stdio

For terminology lookup without a server or personal record, run uvx mirobody mcp. It serves MCP over stdio from the published package. If Mirobody is already installed, mirobody mcp starts the same server. No database or model key is needed for reading, complaint, indicator or unit standardization. In a client that starts local MCP processes, use this configuration:

{
  "mcpServers": {
    "mirobody": {
      "command": "uvx",
      "args": ["mirobody", "mcp"]
    }
  }
}

This server offers standardize_reading for FHIR Observations with LOINC and UCUM codes, standardize_complaint for ICPC-3, and resolve_indicator, normalize_unit and convert_unit for terminology lookup. Its standardize_report tool reads a PDF, image, spreadsheet or text report; that tool additionally needs the mirobody[parse] extra and a configured model key, and sends the document to the chosen model provider. To enable it with uvx, run uvx --from 'mirobody[parse]' mirobody mcp. Use the personal URL above when the client needs a person’s stored health record. The protocol implementation and the per-account filter are in .

​Endpoints

​Personal MCP URL

​Tools an account sees

​Connect a client

​Local terminology over stdio

Endpoints

Personal MCP URL

Tools an account sees

Connect a client

Local terminology over stdio