> ## Documentation Index
> Fetch the complete documentation index at: https://foreverbetter.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents & MCP

> Discover the service, list scoped tools, and call them over MCP or REST.

The API is agent-native. An agent can discover the contract without credentials,
then call scoped tools over MCP JSON-RPC or plain REST.

## Discover the contract

```bash theme={null}
curl -s "$HEALTH_API/.well-known/health-agent.json"
```

The manifest includes the base URL, OTP auth endpoints, required JWT claims,
available REST endpoints, MCP tools, scopes, and endpoint IDs. The OpenAPI 3.1
contract at `GET /openapi.json` is generated from the same schema source the MCP
tools use.

## Get a key

An agent with no credentials can mint one: the manifest's `auth.self_serve_key`
block lists the three calls (start email OTP, verify the user's 8-digit code,
then `POST /api-keys` with the session token). The walkthrough, including a
ready-made MCP config, is at [Connect your agent](/connect-your-agent).

## List tools (scoped to the token)

```bash theme={null}
curl -s -X POST "$HEALTH_API/mcp" \
  -H "authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

`tools/list` returns only the tools allowed by both the token's scopes and its
enabled-endpoint claims, so an agent sees exactly what the user granted.

## Call a tool

```bash theme={null}
curl -s -X POST "$HEALTH_API/mcp" \
  -H "authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "query_health_context",
      "arguments": { "user_id": "user_123", "organization_id": "org_123", "query": "ApoB" }
    }
  }'
```

## Scopes and endpoint grants

Tokens carry scopes (`health:data:read`, `health:data:write`,
`health:connections:write`, `health:labs:read`) and per-endpoint grants. Issue
agents the smallest set they need, for example `imports.file`,
`analyses.create`, `query.create`, and `dashboard_specs.read`. Errors use RFC
9457 Problem Details for REST and structured `error.data` (with `code`, `cause`,
`fix`, `docs_url`, `request_id`) for MCP.