Sentinel Signal MCP

Ferramentas de agente via MCP para pontuação de fluxo de trabalho, limites/uso e feedback (chave de teste suportada)

GitHubExperimente este MCPPatrocinado

Documentação

Sentinel Signal MCP para Pontuação de Reivindicações de Saúde

MCP Badge

Acesso MCP hospedado e local para pontuação de fluxos de trabalho de reivindicações de saúde, uso, limites e feedback.

Hospedado Primeiro

  • Endpoint MCP remoto hospedado: https://mcp.sentinelsignal.io/mcp
  • Listagem Smithery: @sentinelsignal/scoring (https://server.smithery.ai/sentinelsignal/scoring)
  • Chave de teste gratuita sem cadastro: POST https://token.sentinelsignal.io/v1/keys/trial
  • Pacote local: uvx sentinel-signal-mcp

Início Rápido (10 linhas)

uvx sentinel-signal-mcp
export SENTINEL_BASE_URL="https://api.sentinelsignal.io"
export SENTINEL_TOKEN_BASE_URL="https://token.sentinelsignal.io"
# Optional: export SENTINEL_API_KEY="ss_live_or_test_api_key_here"
# If omitted, the MCP server auto-mints a trial key

Endpoint MCP remoto hospedado (HTTP Streamable): https://mcp.sentinelsignal.io/mcp

Listagem hospedada Smithery: @sentinelsignal/scoring (https://server.smithery.ai/sentinelsignal/scoring)

Se o seu cliente MCP suporta MCP HTTP remoto, aponte para essa URL e envie Authorization: Bearer <SENTINEL_API_KEY>. Para conexões hospedadas via Smithery, a chave é encaminhada como x-sentinel-api-key.

Claude Desktop (config MCP plug-and-play)

{
  "mcpServers": {
    "sentinel-signal": {
      "command": "uvx",
      "args": ["sentinel-signal-mcp"],
      "env": {
        "SENTINEL_BASE_URL": "https://api.sentinelsignal.io",
        "SENTINEL_TOKEN_BASE_URL": "https://token.sentinelsignal.io"
      }
    }
  }
}

Cursor (mesmo formato de config MCP)

{
  "mcpServers": {
    "sentinel-signal": {
      "command": "uvx",
      "args": ["sentinel-signal-mcp"],
      "env": {
        "SENTINEL_BASE_URL": "https://api.sentinelsignal.io",
        "SENTINEL_TOKEN_BASE_URL": "https://token.sentinelsignal.io"
      }
    }
  }
}

O Windsurf pode usar o mesmo formato de bloco mcpServers.

Este pacote fornece um servidor MCP stdio local, enquanto o serviço remoto hospedado expõe as mesmas ferramentas de reivindicações de saúde via HTTP Streamable. Ele suporta:

PyPI: https://pypi.org/project/sentinel-signal-mcp/

  • uma SENTINEL_API_KEY fornecida pelo usuário, ou
  • emissão automática de chave de teste sem cadastro (POST /v1/keys/trial) com cache seguro de credenciais local

Habilidades (Ferramentas MCP)

  • list_workflows — lista fluxos de trabalho suportados e versões atuais dos modelos
  • get_workflow_schema — busca campos obrigatórios, campos opcionais e um exemplo de payload para um fluxo de trabalho
  • validate_workflow_payload — valida e normaliza um payload de fluxo de trabalho antes da pontuação
  • score_workflow — pontua risco de negação, autorização prévia e payloads de reembolso contra um fluxo de trabalho nomeado
  • score_batch — pontua até 25 itens de fluxo de trabalho em uma única solicitação
  • get_limits — recupera limites do plano para a chave atual
  • get_usage — recupera uso de um mês específico
  • submit_feedback — envia feedback estruturado de resultados

Início rápido (uvx)

  1. Instale uv (se necessário): https://docs.astral.sh/uv/
  2. Defina variáveis de ambiente (SENTINEL_API_KEY opcional; se omitido, o servidor emite automaticamente uma chave de teste e a armazena em cache):
export SENTINEL_BASE_URL="https://api.sentinelsignal.io"                      # optional (default shown)
export SENTINEL_TOKEN_BASE_URL="https://token.sentinelsignal.io"  # optional (default shown)
# export SENTINEL_API_KEY="ss_live_or_test_api_key_here"                       # optional
export SENTINEL_TIMEOUT_SECONDS="30"                                           # optional
  1. Execute o servidor MCP:
uvx sentinel-signal-mcp

Comportamento esperado: instalar ferramenta -> (opcionalmente definir variáveis de ambiente) -> o agente pode chamar score_workflow.

Se nenhuma chave de API estiver configurada, o servidor MCP resolve as credenciais nesta ordem:

  1. Variável de ambiente SENTINEL_API_KEY
  2. Chave de teste em cache (~/.sentinel/credentials.json por padrão) se não expirada e as URLs base corresponderem
  3. Emitir uma nova chave de teste de POST {SENTINEL_TOKEN_BASE_URL}/v1/keys/trial

Desative o teste automático com SENTINEL_NO_TRIAL=1.

Trechos de configuração do cliente MCP

Claude Desktop (exemplo macOS/Linux)

Adicione isto ao seu JSON de configuração MCP (seção mcpServers):

{
  "mcpServers": {
    "sentinel-signal": {
      "command": "uvx",
      "args": ["sentinel-signal-mcp"],
      "env": {
        "SENTINEL_BASE_URL": "https://api.sentinelsignal.io",
        "SENTINEL_TOKEN_BASE_URL": "https://token.sentinelsignal.io",
        "SENTINEL_API_KEY": "ss_live_or_test_api_key_here",
        "SENTINEL_TIMEOUT_SECONDS": "30"
      }
    }
  }
}

Cliente MCP stdio genérico

Se o seu cliente aceita uma definição de comando + argumentos + env:

  • comando: uvx
  • argumentos: ["sentinel-signal-mcp"]
  • env:
    • SENTINEL_API_KEY opcional (se omitido, a emissão automática de teste é usada, a menos que desativada)
    • SENTINEL_BASE_URL opcional
    • SENTINEL_TOKEN_BASE_URL opcional
    • SENTINEL_CREDENTIALS_PATH opcional
    • SENTINEL_NO_TRIAL=1 opcional
    • SENTINEL_TIMEOUT_SECONDS opcional

Detalhes das ferramentas

list_workflows

Chama GET /v1/workflows para que os agentes possam descobrir os fluxos de trabalho de saúde suportados e as versões atuais dos modelos antes da pontuação.

Sem argumentos.

get_workflow_schema

Chama GET /v1/workflows/{workflow}/schema para que os agentes possam buscar campos obrigatórios, campos opcionais, enums e exemplos de payload antes de emitir uma pontuação.

Argumentos:

  • workflow (str): ID do fluxo de trabalho, como healthcare.denial

validate_workflow_payload

Chama POST /v1/workflows/{workflow}/validate e retorna a saída do payload normalizado mais problemas de validação estruturados sem consumir uma chamada de pontuação.

Argumentos:

  • workflow (str): ID do fluxo de trabalho, como healthcare.denial
  • payload (object): objeto de payload do fluxo de trabalho para validar

score_workflow

Chama o endpoint unificado de pontuação do Sentinel Signal (POST /v1/score).

Argumentos:

  • workflow (str): ID do fluxo de trabalho (por exemplo, healthcare.denial, healthcare.prior_auth, healthcare.reimbursement)
  • payload (object): objeto de payload do fluxo de trabalho
  • options (object, opcional): objeto de opções de pontuação

Exemplo de entrada de chamada de ferramenta MCP:

{
  "workflow": "healthcare.denial",
  "payload": {
    "payer_id": 44,
    "provider_id": 1021,
    "patient_id": "PT_DEMO_001",
    "patient_age": 57,
    "patient_sex": "F",
    "cpt_code": "99214",
    "icd10_code": "M5450",
    "service_date": "2026-02-13",
    "place_of_service": "11",
    "units": 1,
    "billed_amount": 210.0,
    "allowed_amount": 145.0,
    "claim_frequency_code": "1",
    "network_status": "in_network",
    "prior_authorization_required": true,
    "prior_authorization_on_file": false,
    "referral_on_file": false,
    "is_emergency": false,
    "modifier_1": "25",
    "submission_channel": "edi",
    "data_source": "api"
  },
  "options": {
    "allow_fallback": true,
    "distribution_profile": "commercial_beta",
    "operating_point": "high_recall"
  }
}

get_limits

Chama GET /v1/limits para a chave de API atual.

Sem argumentos.

get_usage

Chama GET /v1/usage.

Argumentos:

  • month (str, opcional): filtro de mês (por exemplo, 2026-02)

score_batch

Chama POST /v1/score/batch para pontuar até 25 itens de fluxo de trabalho sequencialmente em uma única solicitação.

Argumentos:

  • items (array): lista de itens de pontuação {workflow, payload, options?}
  • continue_on_error (bool, opcional): se itens posteriores devem continuar se um item anterior falhar

submit_feedback

Chama POST /v1/feedback com um payload de feedback estruturado.

Argumentos:

  • feedback (object): objeto FeedbackRequest bruto

Exemplo de entrada:

{
  "feedback": {
    "request_id": "00000000-0000-0000-0000-000000000001",
    "endpoint": "denial",
    "observed_outcome": "denied",
    "expected_outcome": "paid",
    "confidence_mismatch": true,
    "payer_id": 44,
    "cpt": "99214",
    "denial_reason_code": "AUTH_MISSING",
    "severity": "med",
    "days_to_outcome": 12,
    "notes": "Example feedback payload for agent integration testing."
  }
}

Cache de chave de teste (modo de emissão automática)

Caminho de cache padrão:

  • ~/.sentinel/credentials.json (permissões 0600)

O payload em cache inclui a chave de teste mais metadados usados pelo agente/ambiente de execução:

{
  "api_key": "ss_trial_...",
  "account_id": "uuid",
  "expires_at": "2026-03-10T00:00:00Z",
  "limits": {
    "monthly_quota": 1000,
    "rps": 1,
    "burst": 5
  },
  "upgrade_url": "https://sentinelsignal.io/portal/dashboard",
  "token_base_url": "https://token.sentinelsignal.io",
  "api_base_url": "https://api.sentinelsignal.io"
}

O servidor MCP armazena ambas as URLs base no cache para não reutilizar acidentalmente uma chave de teste em diferentes ambientes.

Redefina as credenciais em cache (força uma nova chave de teste na próxima execução):

uvx sentinel-signal-mcp --reset-credentials

Variáveis de ambiente

  • SENTINEL_BASE_URL (opcional, padrão https://api.sentinelsignal.io): URL base da API de pontuação
  • SENTINEL_TOKEN_BASE_URL (opcional, padrão https://token.sentinelsignal.io): URL base do serviço de token usado para emissão de chave de teste
  • SENTINEL_API_KEY (opcional): se definido, usado diretamente e nunca armazenado em cache
  • SENTINEL_CREDENTIALS_PATH (opcional, padrão ~/.sentinel/credentials.json)
  • SENTINEL_NO_TRIAL (opcional): defina como 1 para desativar a emissão automática de teste
  • SENTINEL_TIMEOUT_SECONDS (opcional, padrão 30)
  • SENTINEL_API_BASE_URL (alias legado para SENTINEL_BASE_URL)

Comportamento de erro para agentes

As ferramentas MCP retornam payloads estruturados tanto para sucesso quanto para falhas operacionais comuns:

  • sucesso -> {"ok": true, ...}

  • cota esgotada / pagamento necessário (402) -> {"ok": false, "error": {"action": "upgrade_required", "upgrade_url": "...", ...}}

  • limite de taxa (429) -> {"ok": false, "error": {"action": "retry_later", ...}}

  • problemas de autenticação/configuração (401/403 ou credenciais ausentes) -> {"ok": false, "error": {"action": "configure_credentials", ...}}

Publicação (caminho Python / uvx)

Este pacote está configurado para publicação no PyPI para que os usuários possam executá-lo com:

uvx sentinel-signal-mcp

Comandos típicos de lançamento:

python -m build
python -m twine upload dist/*

Notas de segurança

  • Não envie chaves de API reais ou payloads de clientes.
  • Use valores de espaço reservado em configurações de cliente e exemplos.
  • Credenciais de teste emitidas automaticamente são armazenadas em cache localmente com permissões de arquivo 0600.
  • Use SENTINEL_CREDENTIALS_PATH=/tmp/... para ambientes efêmeros se você não quiser um cache persistente.