MCP (Model Context Protocol)

O MCP permite integrar um LLM (no lado do hospital) diretamente com as ferramentas da SauBit via um único endpoint padronizado. Em vez de o cliente implementar chamadas REST manualmente, ele conecta no MCP Server e o LLM passa a chamar tools como saubit.interactions_check.

Endpoint

• URL: https://api.saubit.com.br/mcp
• Autenticação: header X-API-Key

Configuração (copiar e colar)

Exemplo de configuração de MCP client (formato comum em ferramentas de IDE/agents):

{
  "mcpServers": {
    "saubit": {
      "type": "http",
      "url": "https://api.saubit.com.br/mcp",
      "headers": {
        "X-API-Key": "SUA_API_KEY"
      },
      "metadata": {
        "name": "saubit-mcp",
        "description": "MCP server da SauBit para ferramentas clínicas (interações, chat, análises, billing/usage)."
      }
    }
  }
}

Segurança

• Use sempre uma API key por organização.
• Se sua API key estiver com whitelist de IP ativa, o MCP também respeita essa regra.
• Para uso em browser, o servidor aplica CORS com base em MCP_ALLOWED_ORIGINS e valida Origin quando presente.
• O tool saubit.interactions_check exige scope interactions:check.
• O tool saubit.chat_message também depende de interactions:check.
• Os tools saubit.analyses_list e saubit.analyses_get exigem analyses:read.
• Os tools saubit.usage_summary e saubit.billing_summary exigem usage:read e billing:read.

CORS (browser)

• Se seu painel roda em http://localhost:3000, inclua esse origin em MCP_ALLOWED_ORIGINS.
• Exemplo: MCP_ALLOWED_ORIGINS=http://localhost:3000,https://seu-dominio.com

Onboarding automático para agentes/IAs (comece aqui)

O servidor MCP se auto-documenta: um agente que acabou de conectar não precisa ler esta página para descobrir o fluxo — ele pode chamar a ferramenta saubit.getting_started (não exige nenhum scope além de uma API key válida) e receber, em JSON estruturado:

• autenticação (header, prefixo sm_test_ vs sm_live_, como obter uma chave);
• a ordem recomendada de chamadas (tools/list → saubit.interactions_check → saubit.chat_message opcional → saubit.analyses_get/saubit.usage_summary opcionais);
• os scopes exigidos por cada ferramenta;
• um exemplo tools/call pronto para copiar e enviar;
• como interpretar os códigos de erro (HTTP e JSON-RPC).

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

O mesmo conteúdo também está disponível como resource MCP, para clientes que preferem resources/read a tools/call:

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

Resources MCP disponíveis (resources/list / resources/read)

URI	Conteúdo
saubit://guide/getting-started	O mesmo guia de integração retornado por saubit.getting_started.
saubit://openapi/hospital.json	Especificação OpenAPI 3 completa de todas as rotas de cliente (X-API-Key) — schema de request/response de cada endpoint, exclui rotas administrativas.

Tools disponíveis

• saubit.getting_started — guia de integração (comece por aqui; sem scope exigido)
• saubit.interactions_check
• saubit.chat_message
• saubit.analyses_list
• saubit.analyses_get
• saubit.usage_summary
• saubit.billing_summary

Notas importantes

• saubit.chat_message aceita analysis_id opcional (mesmo comportamento do REST), para que o chat use a análise como contexto e filtre menções a fontes não verificadas.
• saubit.analyses_get retorna response_body (sem ecoar patient_record/request completo) para reduzir risco de exposição de dados.
• O retorno de saubit.interactions_check usa o mesmo contrato do REST, incluindo analysis_status, source_coverage e unverified_pairs.

Exemplo (JSON-RPC)

Listar 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: <SUA_API_KEY>" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Executar análise de interações

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: <SUA_API_KEY>" \
  -d '{
    "jsonrpc":"2.0",
    "id":2,
    "method":"tools/call",
    "params":{
      "name":"saubit.interactions_check",
      "arguments":{
        "medications":[{"name":"AAS","dose_mg":100},{"name":"Cetorolaco","dose_mg":10}],
        "patient_record":{"conditions":["hipertensao"],"current_medications":[]}
      }
    }
  }'

Exemplo de MCP Client (Node.js)

Este exemplo usa o transport HTTP do MCP e injeta X-API-Key em todas as chamadas.

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: "AAS", dose_mg: 100 }, { name: "Cetorolaco", dose_mg: 10 }],
    patient_record: { conditions: ["hipertensao"], current_medications: [] },
  },
});
console.log(resp);

O que o MCP traz

• Uma integração padronizada de tools (o LLM chama ferramentas, não endpoints).
• Menos boilerplate no cliente (hospital).
• Mesma autenticação (X-API-Key), rate limit e controle de uso já existentes na SauBit.