MCP server

MCP access is available to approved Sandbox projects.

Heyrafiki MCP exposes read-only Practitioner, Booking, Session, Benefits, Claims and remittance tools over the same resource definitions as the REST API.

Endpoint

Heyrafiki implements MCP revision 2026-07-28 over Streamable HTTP. Read the protocol specification.

https://mcp.heyrafiki.space/api/mcp

The protocol is stateless. Current clients send the protocol version and capabilities with every request. New integrations should not depend on an initialize exchange or Mcp-Session-Id.

Connect

Add the remote server

Use the endpoint above in a client that supports MCP 2026-07-28.

Complete OAuth

The server returns protected-resource metadata when authorization is required. The client uses it to discover the authorization server and request the approved scopes.

Discover capabilities

Call server/discover, then tools/list. The available operations are determined by the authenticated Sandbox project and its scopes.

Access tokens are bound to the MCP resource, a Heyrafiki Organization and an approved grant. A token cannot use a tool outside the intersection of its token scopes and grant scopes.

Message format

Every POST includes these HTTP headers:

Header	Value
`MCP-Protocol-Version`	`2026-07-28`
`Mcp-Method`	The JSON-RPC method, such as `server/discover` or `tools/call`
`Mcp-Name`	The tool name for `tools/call`
`Content-Type`	`application/json`

The values in MCP-Protocol-Version, Mcp-Method and Mcp-Name must match the JSON-RPC body. A mismatch is rejected with HeaderMismatch (-32020). Every request also carries protocol metadata inside params._meta:

{
  "io.modelcontextprotocol/protocolVersion": "2026-07-28",
  "io.modelcontextprotocol/clientInfo": {
    "name": "your-client",
    "version": "1.0.0"
  },
  "io.modelcontextprotocol/clientCapabilities": {}
}

Discover the server

After OAuth, call server/discover before invoking a tool.

curl https://mcp.heyrafiki.space/api/mcp \
  -X POST \
  -H "Authorization: Bearer $HEYRAFIKI_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: server/discover" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "server/discover",
    "params": {
      "_meta": {
        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
        "io.modelcontextprotocol/clientInfo": {
          "name": "your-client",
          "version": "1.0.0"
        },
        "io.modelcontextprotocol/clientCapabilities": {}
      }
    }
  }'

Successful results use resultType: "complete". Discovery and tool-list responses also include ttlMs and cacheScope. Treat private results as specific to the authenticated client and project.

Call a tool

curl https://mcp.heyrafiki.space/api/mcp \
  -X POST \
  -H "Authorization: Bearer $HEYRAFIKI_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: tools/call" \
  -H "Mcp-Name: list_practitioners" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "list_practitioners",
      "arguments": { "limit": 10 },
      "_meta": {
        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
        "io.modelcontextprotocol/clientInfo": {
          "name": "your-client",
          "version": "1.0.0"
        },
        "io.modelcontextprotocol/clientCapabilities": {}
      }
    }
  }'

Use an MCP SDK where possible. It adds the required transport headers and per-request metadata for you.

Available tools

Tool	Purpose	Required scope
`list_practitioners`	List Practitioner profiles	`practitioners:read`
`get_practitioner`	Retrieve a Practitioner	`practitioners:read`
`get_practitioner_availability`	Read recurring weekly hours	`availability:read`
`list_bookings`	List Bookings	`bookings:read`
`get_booking`	Retrieve a Booking	`bookings:read`
`list_sessions`	List Sessions	`sessions:read`
`get_session`	Retrieve a Session	`sessions:read`
`list_claims`	List Organization-scoped Claims	`claims:read`
`get_claim`	Retrieve an Organization-scoped Claim	`claims:read`
`get_eligibility_check`	Retrieve an eligibility decision	`benefits:read`
`get_preauthorization`	Retrieve a pre-authorization	`benefits:read`
`list_remittances`	List project-scoped remittances	`remittances:read`
`get_remittance`	Retrieve a remittance	`remittances:read`

Access boundaries

Tools are read-only. Results are limited to the authenticated Sandbox project and Organization. Every request is size-bounded, rate-limited, scoped and recorded in the MCP access audit. Request access for a Sandbox project.

Get started

Integration tools

Endpoint

Connect

Message format

Discover the server

Call a tool

Available tools

Access boundaries

​Endpoint

​Connect

​Message format

​Discover the server

​Call a tool

​Available tools

​Access boundaries

Endpoint

Connect

Message format

Discover the server

Call a tool

Available tools

Access boundaries