bsp-mcp

Connect AI to health data — with verified consent

Published by the Ambrósio Institute · biologicalsovereigntyprotocol.com

What it is

bsp-mcp is the official Model Context Protocol server for the Biological Sovereignty Protocol. It lets any MCP-compatible AI assistant — Claude, GPT, or any other — read and interact with a user's BSP health records. But it never does so silently: every single data access is gated by a ConsentToken that the user explicitly issued, with cryptographic verification enforced on-chain.

The server implements the MCP tool interface over stdio, integrates with the bsp-sdk ExchangeClient, and treats consent as a hard runtime constraint — not a UI checkbox. If a valid token is not present, or if the requested intent falls outside what was authorized, the call is rejected before any data is touched.

Related MCP server: Sensor Bio MCP Server

Why this matters

In 2026, AI health assistants are everywhere. The problem is that most of them access health data through institutional pipelines where the user is a bystander — data flows from EHR to platform to model, and the individual never sees the consent trail, let alone controls it.

BSP-MCP inverts that. Every query your AI makes is gated by a ConsentToken you issued, scoped to exactly the categories and intents you authorized, with an expiry you set. The AI sees what you allowed — nothing more. When you revoke access, it stops immediately. The entire access history is permanently recorded on Aptos, auditable by anyone.

This is what sovereign health data looks like in practice.

Available Tools

Setup

1. Install

npx bsp-mcp

2. Configure in Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "bsp": {
      "command": "npx",
      "args": ["-y", "bsp-mcp"],
      "env": {
        "BSP_BEO_DOMAIN": "yourname.bsp",
        "BSP_CONSENT_TOKEN_ID": "tok_...",
        "BSP_NETWORK": "mainnet"
      }
    }
  }
}

3. Issue a ConsentToken

Before your AI can read any records, you need to authorize it from your BSP identity:

bsp consent grant \
  --beo yourname.bsp \
  --intent READ_RECORDS \
  --categories BSP-HM,BSP-GL,BSP-LA \
  --expires 2026-12-31 \
  --output tok_...

Then set that token ID as BSP_CONSENT_TOKEN_ID in the server env.

4. Verify the connection

Start a Claude session and ask:

"Check my BSP consent status"

Claude will call bsp_check_consent and confirm which BEO is connected and what data it can access.

Demo conversation

User: Analyze my latest blood panel results

Claude: Let me check your BSP consent first.

  [bsp_check_consent]
  → BEO: alice.bsp
  → Token: tok_7f3a...c291
  → Network: mainnet
  → Intents: READ_RECORDS
  → Authorized categories: BSP-HM (Hematology), BSP-GL (Genomics Light), BSP-LA (Lab – Advanced)
  → Expires: 2026-12-31

  Consent verified. Fetching your hematology records.

  [bsp_get_biorecords]
  → BEO: alice.bsp
  → Category: BSP-HM
  → Date range: last 90 days
  → Records returned: 12

Based on your latest blood panel (March 18, 2026):

  Hemoglobin     14.2 g/dL   ✓  normal (ref: 12.0–16.0)
  Hematocrit     42.1 %      ✓  normal (ref: 36–48)
  WBC            7,200 /μL   ✓  normal (ref: 4,500–11,000)
  Platelets      238,000 /μL ✓  normal (ref: 150,000–400,000)
  MCV            88 fL       ✓  normal (ref: 80–100)
  Ferritin       22 ng/mL    ⚠  low-normal (ref: 20–200; optimal longevity: >50)

Everything is within clinical range. Ferritin at 22 ng/mL is technically normal,
but for longevity optimization the target is typically above 50. Worth discussing
iron supplementation or dietary adjustments with your provider.

Security model

How consent verification works

The ConsentGuard runs before every data-access tool call. It checks that:

1. A BEO domain is configured (BSP_BEO_DOMAIN)

2. A ConsentToken is present (BSP_CONSENT_TOKEN_ID)

3. The token's intents array includes the required intent for the requested operation

4. The token has not expired

When bsp-sdk is connected to the registry, step 3 and 4 are verified on-chain against the AccessControl contract. The token state on Aptos is the source of truth — not the local environment.

What happens when a token expires

[bsp_get_biorecords]
⛔ BSP Consent Error [TOKEN_EXPIRED]

The ConsentToken tok_7f3a...c291 expired on 2026-06-01.
The BEO holder must issue a new token to continue.
→ https://biologicalsovereigntyprotocol.com/getting-started/quickstart

The AI cannot proceed. No data is returned. No fallback path exists.

What happens when a token is revoked

Revocation is immediate. The AccessControl contract on Aptos marks the token as revoked, and the next tool call that hits the registry will receive a TOKEN_REVOKED error and halt. Mid-conversation revocation is handled gracefully — the AI acknowledges the revocation and stops accessing data.

Scope enforcement

Tokens are scoped. A token with READ_RECORDS on BSP-HM,BSP-GL cannot be used to read BSP-CV (cardiovascular) data even if that category exists in the BEO. Category-level enforcement is delegated to the AccessControl contract.

For developers

Adding a new tool

Tools are registered in src/index.ts. Each tool follows this pattern:

// 1. Define the tool in the tools[] array
{
  name: 'bsp_my_new_tool',
  description: '...',
  inputSchema: { type: 'object', properties: { ... } }
}

// 2. Add a case in the CallToolRequestSchema handler
case 'bsp_my_new_tool': {
  // For consent-required tools:
  const consentError = guard.check('REQUIRED_INTENT')
  if (consentError) return consentError

  // Your tool logic here
  // Use bsp-sdk ExchangeClient to interact with the registry
}

Tool interface

Every tool returns an MCPResult:

type MCPResult = {
  content: Array<{ type: 'text'; text: string }>
  isError?: boolean
}

Environment variables

Related packages

• bsp-spec — full BSP specification

• bsp-sdk-typescript — TypeScript SDK (bsp-sdk)

• bsp-id-web — web app to manage your BEO and issue tokens

Tool Schemas

Exhaustive JSON Schema for every tool. For end-to-end request / response examples with success and error paths, see examples/.

bsp_check_consent

{ "type": "object", "properties": {}, "required": [] }

bsp_get_biorecords

{
  "type": "object",
  "properties": {
    "category":  { "type": "string",  "description": "BSP category code (e.g. BSP-HM)" },
    "codes":     { "type": "array",   "items": { "type": "string" }, "description": "Specific biomarker codes" },
    "fromDate":  { "type": "string",  "format": "date-time" },
    "toDate":    { "type": "string",  "format": "date-time" },
    "limit":     { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 }
  },
  "required": []
}

bsp_get_beo_summary

{ "type": "object", "properties": {}, "required": [] }

bsp_resolve_biomarker

{
  "type": "object",
  "properties": {
    "code": { "type": "string", "description": "Biomarker code (e.g. BSP-HM-HGB)" }
  },
  "required": ["code"]
}

bsp_list_categories

{
  "type": "object",
  "properties": {
    "level": {
      "type": "string",
      "enum": ["CORE", "STANDARD", "EXTENDED", "DEVICE"]
    }
  },
  "required": []
}

bsp_lock_beo / bsp_unlock_beo

{
  "type": "object",
  "properties": {
    "confirm": { "type": "boolean", "description": "Must be true" }
  },
  "required": ["confirm"]
}

bsp_destroy_beo

{
  "type": "object",
  "properties": {
    "confirm": { "type": "boolean", "description": "Must be true — irreversible" },
    "reason":  { "type": "string",  "description": "Optional audit reason" }
  },
  "required": ["confirm"]
}

bsp_revoke_all_tokens

{
  "type": "object",
  "properties": {
    "confirm": { "type": "boolean" }
  },
  "required": ["confirm"]
}

All tools return an MCPResult:

type MCPResult = {
  content: Array<{ type: 'text'; text: string }>
  isError?: boolean
}

Error payloads always include a stable code in brackets — e.g. [TOKEN_EXPIRED], [SCOPE_VIOLATION], [CONFIRM_REQUIRED]. Full catalog: bsp-spec/docs/ERROR_CODES.md.

Changelog

See CHANGELOG.md.

Contributing

See CONTRIBUTING.md.

License

Apache 2.0 — Ambrósio Institute