sentinel-signal-mcp 0.1.5

Hosted and local MCP tools for healthcare claims workflow scoring, usage, limits, and feedback

Sentinel Signal MCP for Healthcare Claims Scoring

Hosted and local MCP access for healthcare claims workflow scoring, usage, limits, and feedback.

Hosted First

• Hosted remote MCP endpoint: https://mcp.sentinelsignal.io/mcp
• Smithery listing: @sentinelsignal/scoring (https://server.smithery.ai/sentinelsignal/scoring)
• Free no-signup trial key: POST https://token.sentinelsignal.io/v1/keys/trial
• Local package: uvx sentinel-signal-mcp

Quickstart (10 lines)

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

Hosted remote MCP endpoint (Streamable HTTP): https://mcp.sentinelsignal.io/mcp

Smithery hosted listing: @sentinelsignal/scoring (https://server.smithery.ai/sentinelsignal/scoring)

If your MCP client supports remote HTTP MCP, point it at that URL and send Authorization: Bearer <SENTINEL_API_KEY>. For Smithery-hosted connections, the key is forwarded as x-sentinel-api-key.

Claude Desktop (drop-in MCP config)

{
  "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 (same MCP config shape)

{
  "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"
      }
    }
  }
}

Windsurf can use the same mcpServers block shape.

This package provides a local stdio MCP server, while the hosted remote service exposes the same healthcare claims tools over Streamable HTTP. It supports either:

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

• a user-provided SENTINEL_API_KEY, or
• automatic no-signup trial key minting (POST /v1/keys/trial) with secure local credential caching

Skills (MCP Tools)

• list_workflows — list supported workflows and current model versions
• get_workflow_schema — fetch required fields, optional fields, and an example payload for a workflow
• validate_workflow_payload — validate and normalize a workflow payload before scoring
• score_workflow — score denial risk, prior auth, and reimbursement payloads against a named workflow
• score_batch — score up to 25 workflow items in one request
• get_limits — retrieve plan limits for the current key
• get_usage — retrieve usage for a given month
• submit_feedback — submit structured outcome feedback

Quick start (uvx)

1. Install uv (if needed): https://docs.astral.sh/uv/
2. Set env vars (optional SENTINEL_API_KEY; if omitted, the server auto-mints a trial key and caches it):

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

3. Run the MCP server:

uvx sentinel-signal-mcp

Deliverable behavior: install tool -> (optionally set env vars) -> agent can call score_workflow.

If no API key is configured, the MCP server resolves credentials in this order:

1. SENTINEL_API_KEY env var
2. cached trial key (~/.sentinel/credentials.json by default) if not expired and base URLs match
3. mint a new trial key from POST {SENTINEL_TOKEN_BASE_URL}/v1/keys/trial

Disable auto-trial with SENTINEL_NO_TRIAL=1.

MCP client config snippets

Claude Desktop (macOS/Linux example)

Add this to your MCP config JSON (mcpServers section):

{
  "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"
      }
    }
  }
}

Generic MCP stdio client

If your client accepts a command + args + env definition:

• command: uvx
• args: ["sentinel-signal-mcp"]
• env:
  • optional SENTINEL_API_KEY (if omitted, auto-trial mint is used unless disabled)
  • optional SENTINEL_BASE_URL
  • optional SENTINEL_TOKEN_BASE_URL
  • optional SENTINEL_CREDENTIALS_PATH
  • optional SENTINEL_NO_TRIAL=1
  • optional SENTINEL_TIMEOUT_SECONDS

Tool details

list_workflows

Calls GET /v1/workflows so agents can discover the supported healthcare workflows and current model versions before scoring.

No arguments.

get_workflow_schema

Calls GET /v1/workflows/{workflow}/schema so agents can fetch required fields, optional fields, enums, and example payloads before issuing a score.

Arguments:

• workflow (str): workflow ID such as healthcare.denial

validate_workflow_payload

Calls POST /v1/workflows/{workflow}/validate and returns normalized payload output plus structured validation issues without consuming a scoring call.

Arguments:

• workflow (str): workflow ID such as healthcare.denial
• payload (object): workflow payload object to validate

score_workflow

Calls the Sentinel Signal unified scoring endpoint (POST /v1/score).

Arguments:

• workflow (str): workflow ID (for example healthcare.denial, healthcare.prior_auth, healthcare.reimbursement)
• payload (object): workflow payload object
• options (object, optional): scoring options object

Example MCP tool call input:

{
  "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

Calls GET /v1/limits for the current API key.

No arguments.

get_usage

Calls GET /v1/usage.

Arguments:

• month (str, optional): month filter (for example 2026-02)

score_batch

Calls POST /v1/score/batch to score up to 25 workflow items sequentially in one request.

Arguments:

• items (array): list of {workflow, payload, options?} scoring items
• continue_on_error (bool, optional): whether later items should continue if an earlier item fails

submit_feedback

Calls POST /v1/feedback with a structured feedback payload.

Arguments:

• feedback (object): raw FeedbackRequest object

Example input:

{
  "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."
  }
}

Trial key caching (auto-mint mode)

Default cache path:

• ~/.sentinel/credentials.json (permissions 0600)

Cached payload includes the trial key plus metadata used by the agent/runtime:

{
  "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"
}

The MCP server stores both base URLs in the cache so it does not accidentally reuse a trial key across different environments.

Reset the cached credentials (force a fresh trial key next run):

uvx sentinel-signal-mcp --reset-credentials

Environment variables

• SENTINEL_BASE_URL (optional, default https://api.sentinelsignal.io): scoring API base URL
• SENTINEL_TOKEN_BASE_URL (optional, default https://token.sentinelsignal.io): token-service base URL used for trial key minting
• SENTINEL_API_KEY (optional): if set, used directly and never cached
• SENTINEL_CREDENTIALS_PATH (optional, default ~/.sentinel/credentials.json)
• SENTINEL_NO_TRIAL (optional): set to 1 to disable auto-trial minting
• SENTINEL_TIMEOUT_SECONDS (optional, default 30)
• SENTINEL_API_BASE_URL (legacy alias for SENTINEL_BASE_URL)

Error behavior for agents

The MCP tools return structured payloads for both success and common operational failures:

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

• quota exhausted / payment required (402) -> {"ok": false, "error": {"action": "upgrade_required", "upgrade_url": "...", ...}}

• rate limited (429) -> {"ok": false, "error": {"action": "retry_later", ...}}

• auth/config issues (401/403 or missing credentials) -> {"ok": false, "error": {"action": "configure_credentials", ...}}

Publishing (Python / uvx path)

This package is set up for PyPI publishing so users can run it with:

uvx sentinel-signal-mcp

Typical release commands:

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

Security notes

• Do not commit real API keys or customer payloads.
• Use placeholder values in client configs and examples.
• Auto-minted trial credentials are cached locally with file permissions 0600.
• Use SENTINEL_CREDENTIALS_PATH=/tmp/... for ephemeral environments if you do not want a persistent cache.