MCP (Model Context Protocol)

MCP lets you integrate an LLM (on the hospital side) directly with SauBit's tools via a single standardized endpoint. Instead of the client implementing REST calls manually, it connects to the MCP Server and the LLM calls tools like saubit.interactions_check.

Endpoint

• URL: https://api.saubit.com.br/mcp
• Authentication: X-API-Key header

Configuration (copy & paste)

Example MCP client configuration (a common format in IDE/agent tools):

{
  "mcpServers": {
    "saubit": {
      "type": "http",
      "url": "https://api.saubit.com.br/mcp",
      "headers": {
        "X-API-Key": "YOUR_API_KEY"
      },
      "metadata": {
        "name": "saubit-mcp",
        "description": "SauBit MCP server for clinical tools (interactions, chat, analyses, billing/usage)."
      }
    }
  }
}

Security

• Always use one API key per organization.
• If your API key has an IP allowlist enabled, MCP also respects that rule.
• For browser usage, the server applies CORS based on MCP_ALLOWED_ORIGINS and validates Origin when present.
• The saubit.interactions_check tool requires the interactions:check scope.
• The saubit.chat_message tool also depends on interactions:check.
• The saubit.analyses_list and saubit.analyses_get tools require analyses:read.
• The saubit.usage_summary and saubit.billing_summary tools require usage:read and billing:read.

CORS (browser)

• If your panel runs on http://localhost:3000, include that origin in MCP_ALLOWED_ORIGINS.
• Example: MCP_ALLOWED_ORIGINS=http://localhost:3000,https://your-domain.com

Self-onboarding for agents/AIs (start here)

The MCP server is self-documenting: an agent that just connected doesn't need to read this page to discover the flow — it can call the saubit.getting_started tool (requires no scope beyond a valid API key) and get, as structured JSON:

• authentication (header, sm_test_ vs sm_live_ prefixes, how to get a key);
• the recommended call order (tools/list → saubit.interactions_check → optional saubit.chat_message → optional saubit.analyses_get/saubit.usage_summary);
• the scopes required per tool;
• a ready-to-copy tools/call example;
• how to interpret error codes (HTTP and JSON-RPC).

curl -X POST "https://api.saubit.com.br/mcp" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"saubit.getting_started","arguments":{}}}'

The same content is also available as an MCP resource, for clients that prefer resources/read over tools/call:

curl -X POST "https://api.saubit.com.br/mcp" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -d '{"jsonrpc":"2.0","id":1,"method":"resources/read","params":{"uri":"saubit://guide/getting-started"}}'

Available MCP resources (resources/list / resources/read)

URI	Content
saubit://guide/getting-started	The same integration guide returned by saubit.getting_started.
saubit://openapi/hospital.json	Full OpenAPI 3 spec for every client route (X-API-Key) — request/response schema per endpoint, excludes admin routes.

Available tools

• saubit.getting_started — integration guide (start here; no scope required)
• saubit.interactions_check
• saubit.chat_message
• saubit.analyses_list
• saubit.analyses_get
• saubit.usage_summary
• saubit.billing_summary

Important notes

• saubit.chat_message accepts an optional analysis_id (same behavior as REST), so the chat uses the analysis as context and filters mentions of unverified sources.
• saubit.analyses_get returns response_body (without echoing the full patient_record/request) to reduce data-exposure risk.
• The saubit.interactions_check return uses the same contract as REST, including analysis_status, source_coverage and unverified_pairs.

Example (JSON-RPC)

List tools

curl -X POST "https://api.saubit.com.br/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":"tools/list","params":{}}'

Run an interactions analysis

curl -X POST "https://api.saubit.com.br/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":2,
    "method":"tools/call",
    "params":{
      "name":"saubit.interactions_check",
      "arguments":{
        "medications":[{"name":"Aspirin","dose_mg":100},{"name":"Ketorolac","dose_mg":10}],
        "patient_record":{"conditions":["hypertension"],"current_medications":[]}
      }
    }
  }'

MCP Client example (Node.js)

This example uses the MCP HTTP transport and injects X-API-Key on every call.

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(new URL("https://api.saubit.com.br/mcp"), {
  headers: {
    "X-API-Key": process.env.SAUBIT_API_KEY!,
  },
});

const client = new Client({ name: "hospital-client", version: "1.0.0" }, { capabilities: {} });
await client.connect(transport);

const tools = await client.listTools();
console.log(tools);

const resp = await client.callTool({
  name: "saubit.interactions_check",
  arguments: {
    medications: [{ name: "Aspirin", dose_mg: 100 }, { name: "Ketorolac", dose_mg: 10 }],
    patient_record: { conditions: ["hypertension"], current_medications: [] },
  },
});
console.log(resp);

What MCP brings

• A standardized tool integration (the LLM calls tools, not endpoints).
• Less boilerplate on the client (hospital) side.
• The same authentication (X-API-Key), rate limit and usage control already present in SauBit.