Skip to content

MCP Server

The Levelcast MCP (Model Context Protocol) server lets AI assistants — like Claude Desktop, Cursor or VS Code — read your glucose data, manage your automation rules and trigger actions using your own data.

Endpoint

{BASE_URL}/mcp

Authentication

The MCP server authenticates with an existing API key sent as the x-api-key header (or Authorization: Bearer). The server can only access the patients linked to that API key — the same security model as the public API.

  1. Create an API key from Developers → API and link at least one patient to it.
  2. Configure your MCP client with the endpoint URL and the key.

The full key value is shown only once when the key is created — copy it then. Keys have scopes (read, write): read-only keys can list data and generate reports but cannot create, update or delete anything. test_rule executes the rule’s actions for real, so it requires write scope.

Client configuration

Claude Desktop

Add the server to claude_desktop_config.json:

{
"mcpServers": {
"levelcast": {
"type": "http",
"url": "https://api.levelcast.org/mcp",
"headers": {
"x-api-key": "YOUR_API_KEY"
}
}
}
}

Cursor

Create a .cursor/mcp.json file in your project:

{
"mcpServers": {
"levelcast": {
"type": "http",
"url": "https://api.levelcast.org/mcp",
"headers": {
"x-api-key": "YOUR_API_KEY"
}
}
}
}

VS Code

Create a .vscode/mcp.json file:

{
"servers": {
"levelcast": {
"type": "http",
"url": "https://api.levelcast.org/mcp",
"headers": {
"x-api-key": "YOUR_API_KEY"
}
}
}
}

OpenCode

Add the server to your opencode.json:

{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"levelcast": {
"type": "remote",
"url": "https://api.levelcast.org/mcp",
"enabled": true,
"headers": {
"x-api-key": "YOUR_API_KEY"
}
}
}
}

MCP Inspector

Terminal window
npx @modelcontextprotocol/inspector

Then connect to the endpoint URL with the x-api-key header.

Available capabilities

The server exposes:

  • Tools — actions the assistant can take (automations, glucose data, patients, integrations, WebSocket channels, exports, uploader boxes, reports and insights). Webhooks are rule actions: use integrationServiceId: "webhook" (see list_integration_services for the payload shape).
  • Resources — readable context such as patients, readings, rules and uploader boxes.
  • Prompts — ready-made workflows such as reviewing a patient’s day, generating a weekly summary, or running an uploader health check.

To see the full, always-up-to-date catalog, fetch:

GET /api/v1/mcp/manifest

Automations example

The most powerful use case is letting the assistant manage your automation rules in natural language:

  1. list_integrations — see which accounts (Telegram, Nightscout, Home Assistant…) are connected.
  2. list_patients — choose the patient.
  3. create_rule — create the IF/THEN rule, e.g. “alert me when glucose exceeds 200”.
  4. test_rule — verify it fires correctly.

Uploader boxes

Self-hosted uploader boxes (the devices that sync CGM readings) are manageable through MCP with read and write tools:

  1. list_uploader_boxes — see every box for the linked patients: online/live status, sync interval, provider sync state and pending commands.
  2. get_uploader_box — full status of one box when readings stop arriving.
  3. list_uploader_commands — recent command history (sanitized, never contains credentials).
  4. send_uploader_command — queue poll-now (force an immediate sync), set-poll-interval or set-provider-enabled (pause/resume a glucose provider). write scope required.

Credential provisioning (sealed envelopes) and direct/e2e mode switches stay dashboard-only: the assistant will tell you to do them in the web UI instead. The uploader_health_check prompt walks through the whole diagnosis in one go.

Managed cloud connections

The hosted LibreLinkUp/Dexcom polling connections are diagnosable through MCP with read-only tools (no login, password or token is ever exposed):

  1. list_cloud_connections — every cloud connection for the key owner: status, failure cause in plain language (diagnosis + diagnosisState), and the scheduled automatic retry (nextRetryAt).
  2. get_cloud_connection — full safe detail of one connection (error text, grace counters, egress kind, poll queue state).
  3. cloud_poll_queue — upcoming polls ordered by scheduled time, including whether each job is currently locked (being polled right now).

Example: “why did my LibreLinkUp stop syncing?” → list_cloud_connections shows account-blocked with the Abbott anti-bot explanation and the next automatic retry time.

Example

Connect with curl:

Terminal window
curl -X POST "https://api.levelcast.org/mcp" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2025-06-18",
"capabilities": {},
"clientInfo": { "name": "curl", "version": "1.0" }
}
}'

Security

  • Every tool call is logged in the same audit trail as public API calls.
  • Access is strictly scoped to the patients linked to your API key.
  • Disabling or deleting the API key immediately revokes MCP access.