Pular para o conteúdo
Início

Superfície pública para agentes de IA — endpoints, erros e limites

O Sinthoma expõe um conjunto pequeno e deliberado de endereços para agentes de IA e desenvolvedores. A descoberta (OpenAPI, server card, metadados OAuth) é pública e não exige credencial. O acesso a dado de paciente existe por um único caminho — o Conector MCP — e é sempre autenticado, somente leitura, com consentimento do paciente e auditoria de cada acesso.

Endpoints públicos

Tudo abaixo é servido pela origem canônica (https://sinthoma.com.br). O spec OpenAPI é a verdade técnica sobre cada um; esta tabela é o mapa.

EndpointO que devolveAutenticação
GET /openapi.jsonSpec OpenAPI 3.1 da superfície pública: descoberta, metadados OAuth e o transporte MCP, com os erros 401, 403, 404 e 429 documentados por rota.Nenhuma
GET /mcp/server-cardServer card MCP (application/mcp-server-card+json): nome, descrição, versão, revisões de protocolo e endereço do endpoint remoto.Nenhuma
GET /.well-known/mcpMesmo server card, no formato de descoberta por domínio (application/json).Nenhuma
GET /.well-known/oauth-protected-resourceMetadados do recurso protegido (RFC 9728): escopos, métodos de bearer e onde está o servidor de autorização. Servido também com o sufixo do recurso (/api/mcp).Nenhuma
GET /.well-known/oauth-authorization-serverMetadados do servidor de autorização (RFC 8414): authorize, token, registro dinâmico de cliente (RFC 7591) e PKCE S256 obrigatório.Nenhuma
GET /llms.txtÍndice do site em Markdown para agentes (convenção llmstxt.org): quando usar, quando NÃO usar, limites de segurança e recuperação de erro.Nenhuma
POST /api/mcpTransporte MCP Streamable HTTP (JSON-RPC 2.0), stateless. A descoberta das ferramentas é pelo próprio protocolo: initialize → tools/list → tools/call. Somente leitura; toda leitura é auditada.Token pessoal (sinth_…) ou OAuth 2.0

O que exige credencial — e o que recusa sem ela

Erros e o que significam

A mesma orientação que o agente recebe em /llms.txt — escrita aqui para quem está depurando uma integração.

CódigoSignificadoO que fazer
401Sem credencial ou credencial inválida no endpoint MCP.O desafio WWW-Authenticate aponta /.well-known/oauth-protected-resource. A profissional emite o token dentro do Sinthoma (Configurações → Conector) ou segue o fluxo OAuth por consentimento. Não repita a chamada sem credencial nova.
403Credencial válida, mas sem o escopo que a ferramenta exige — ou paciente sem consentimento de uso de IA.A recusa é intencional e fica registrada na auditoria. Comunique a limitação a quem pergunta; não tente contornar.
404O caminho não existe.Volte ao índice (/llms.txt ou /sitemap.xml) e refaça o caminho. Pedindo com Accept: text/markdown, a resposta também vem em Markdown.
405Método não suportado na rota — /api/mcp só aceita POST; as rotas de descoberta respondem a GET, HEAD e OPTIONS.Confira o método. Nas rotas de descoberta, o 405 vem com corpo problem+json (RFC 9457) e o cabeçalho Allow aponta os métodos aceitos. Listar ferramentas é pelo protocolo (tools/list), não por GET no endpoint.
429Quota ou rate limit do token esgotados.Aguarde alguns segundos e tente de novo. Não é erro permanente.

Uma requisição, e o erro de quem chega sem credencial

A descoberta de ferramentas é pelo próprio protocolo MCP — o mesmo endpoint responde a tools/list e, com a ferramenta escolhida, a tools/call. Sem credencial, a resposta é 401 no formato do RFC 6750 (OAuth 2.0 Bearer), com o desafio WWW-Authenticate apontando os metadados de autorização:

curl -X POST https://sinthoma.com.br/api/mcp \
  -H "Authorization: Bearer sinth_TOKEN_DA_PROFISSIONAL" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
HTTP/1.1 401 Unauthorized
Content-Type: application/json
WWW-Authenticate: Bearer resource_metadata="https://sinthoma.com.br/.well-known/oauth-protected-resource"

{"error":"invalid_token","error_description":"No authorization provided"}

O corpo é curto de propósito: diz que a credencial é o problema, e para onde ir. Erros HTTP das rotas públicas de descoberta (por exemplo, 405 de método não suportado) usam o formato de problema application/problem+json (RFC 9457) e nunca incluem detalhe de infraestrutura.

Versão e descontinuação

Quer ligar um assistente ao prontuário?

O caminho é o Conector MCP: a profissional gera o acesso em Configurações → Conector, conecta no assistente dela (Claude Code, VS Code com Copilot e Grok CLI são os testados até agora) e pergunta em linguagem natural. A resposta traz o trecho literal com a âncora da sessão — nunca um resumo inventado. A página do conector também traz a tabela de compatibilidade, com o estado honesto de cada cliente, incluindo o que ainda não testamos.

Os documentos, direto nos endereços

Entender o Conector MCPAbrir o OpenAPI

Página revisada em 29/08/2026. Compatibilidade de assistentes é mantida em /conector; este índice aponta, não duplica.