Labsco
sentinelsignal logo

Sentinel Signal MCP

from sentinelsignal

Agent tools via MCP for workflow scoring, limits/usage, and feedback (trial key supported)

🔥🔥🔥✓ VerifiedAccount requiredNeeds API keys
#automation#payments#security

Sentinel Signal MCP for Healthcare Claims Scoring

MCP Badge

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

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

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.