Pidgeon MCP Server

MCP server for the Pidgeon Healthcare Interoperability Platform. Connect Claude Desktop, Cursor, VS Code, or any MCP-compatible AI client to Pidgeon's HL7/FHIR/NCPDP engine — generate test messages, validate interfaces, de-identify PHI, diff environments, monitor live interfaces, and more through conversation.

21 tools. 6 guided prompts. 5 reference resources. Automatic tier gating.

Machine-readable surface: MANIFEST.md (generated by npm run manifest). One-click Claude Desktop install: bundle/ (.mcpb).

Quick Start

1. Install the Pidgeon CLI

dotnet tool install -g pidgeon

2. Add to your AI client

Pick your client below, paste the config, restart.

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "pidgeon": {
      "command": "npx",
      "args": ["-y", "@pidgeonhealth/mcp"],
      "env": {
        "PIDGEON_MODE": "cli"
      }
    }
  }
}

Cursor

Open Settings > MCP Servers, click "Add new MCP server", then paste:

{
  "pidgeon": {
    "command": "npx",
    "args": ["-y", "@pidgeonhealth/mcp"],
    "env": {
      "PIDGEON_MODE": "cli"
    }
  }
}

VS Code (Claude Extension)

Add to your .vscode/settings.json or user settings:

{
  "claude.mcpServers": {
    "pidgeon": {
      "command": "npx",
      "args": ["-y", "@pidgeonhealth/mcp"],
      "env": {
        "PIDGEON_MODE": "cli"
      }
    }
  }
}

3. Verify

Ask Claude: "Use pidgeon to generate an ADT A01 message"

You should get a complete HL7 v2 admission message with realistic patient demographics.

What You Can Do

Once connected, talk to Claude naturally:

• "Generate 10 ADT^A01 messages with Epic patterns and save them"
• "Validate this HL7 message and tell me what's wrong: MSH|^~\&|..."
• "What does this HL7 message mean?" (paste any message)
• "Look up LOINC code 2823-3 — what test is that?"
• "De-identify this message — strip all PHI"
• "Diff these two HL7 messages and show me what changed"
• "Run an admit-lab-discharge workflow and generate all the messages"
• "Show me the health status of my Loft interfaces"
• "Generate a population of 500 patients in Illinois"
• "Help me debug why this message is failing" (triggers debug_hl7_error prompt)

Tools

Free Tier

Available to all users — no subscription required.

| Tool | What It Does | Example | |------|-------------|---------| | generate_message | Generate synthetic HL7/FHIR/NCPDP messages. 278 trigger events, 22 FHIR resource types, NCPDP SCRIPT support. | "Generate 5 ORU^R01 lab results" | | validate_message | Validate against HL7/FHIR/NCPDP specs. Strict and compatibility modes. Returns field-level errors with conformance score. | "Validate this message in strict mode" | | explain_message | Parse any HL7 or FHIR message and explain it in plain English. Identifies segments, patient info, and clinical meaning. | "Explain what this message is doing" | | explain_error | Triage a validation/conformance failure: for each finding, what's wrong, why the rule exists, and the concrete fix. On-device, no key. | "Why was this message rejected and how do I fix it?" | | lookup_code | Look up LOINC, ICD-10, ICD-9, NDC, CVX, RxNorm, CPT, or SNOMED codes. Embedded reference data with fuzzy search. | "Look up ICD-10 code E11.9" | | get_segment_spec | HL7 segment field specs — names, data types, lengths, required/optional. Covers MSH, PID, PV1, OBX, OBR, ORC, RXE, DG1, EVN, NK1. | "Show me the OBX segment spec" | | deidentify_message | Strip PHI from HL7 messages. Replaces names, MRNs, dates, addresses, SSNs with synthetic values. | "De-identify this HL7 message" | | manage_data_packages | List, install, or remove clinical reference datasets (LOINC, ICD-10, SNOMED, RxNorm, etc.). | "What data packages are installed?" | | pidgeon_status | Check environment health — CLI, Bridge, .NET SDK, mode, tier — and get setup instructions for anything missing. | "Is my Pidgeon setup healthy?" | | describe_tool | Return any tool's full contract on demand — description, input schema, output-envelope keys, and the error codes it can return. Works in any MCP client; describes Pro tools without unlocking them. | "Describe the generate_message tool" |

Pro Tier

Require a Pro subscription. Free users see a friendly upgrade message with instructions.

| Tool | What It Does | Example | |------|-------------|---------| | diff_messages | Field-level comparison of two HL7 messages. Flags structural, data, and cosmetic differences with severity. | "Diff these two ADT messages" | | analyze_vendor_pattern | Detect vendor (Epic, Cerner, etc.) from message samples. Extracts characteristic field patterns and frequencies. | "Analyze these messages — what vendor sent them?" | | run_workflow | Execute a multi-step clinical scenario (e.g. admission-with-labs) as one coherent patient cohort — a coordinated message sequence sharing one patient. | "Run an admission-with-labs workflow" | | send_message | Deliver HL7 messages to SFTP, Mirth pickup folders, or local file paths. | "Send this message to /mirth/pickup" | | loft_status | Check Loft interface health — per-channel status, message counts, error rates. | "Show me my interface health" | | generate_population | Start a synthetic patient-population job with realistic demographics for a given location (async in Bridge mode). | "Generate 100 patients in Illinois" | | population_status | Poll a population job started by generate_population — progress, counts, completion. | "Is population job abc123 done yet?" | | refine_hl7_segment | Apply a natural-language edit to one HL7 segment, then validate and self-heal it against the spec. | "Set the WBC in this OBX to 18.5" | | conform | Probe a live FHIR endpoint for IG conformance (US Core, Da Vinci PAS/CRD/DTR) — the CMS-0057-F readiness scorecard. Single probe or full endpoint walk. | "Run a CMS-0057-F conformance check on this FHIR endpoint" |

Tier Gating

All 21 tools are always visible — Claude can discover and describe any tool, including the free describe_tool meta-tool that returns any tool's full contract (schema, output-envelope keys, error codes) on demand. When a free-tier user calls a Pro tool, they get a clear upgrade message instead of an error:

**Pidgeon Pro required**

The `diff_messages` tool requires a Pro subscription.

Your current tier: free

Upgrade at: https://pidgeon.health/upgrade

Already a subscriber? Authenticate with the Bridge:
  1. Set PIDGEON_MODE=bridge in your MCP config
  2. Start the Bridge: dotnet run --project pidgeon-cli/src/Pidgeon.Bridge
  3. Run: pidgeon auth login

Prompts

Guided multi-step workflows triggered by natural conversation:

| Prompt | When to Use | What It Does | |--------|------------|-------------| | debug_hl7_error | Message rejected by destination system | Validates, explains each error, identifies root cause, suggests fixes with before/after | | go_live_prep | Preparing for a vendor go-live | Generates vendor-specific test messages, validates against vendor profile, produces testing checklist | | onboard_vendor_interface | New vendor interface setup | Analyzes sample messages, identifies vendor patterns, builds reusable validation profile | | stand_up_interface | Standing up a new conformant interface | Generate → validate → conform (CMS-0057-F gate) → deliver, end-to-end | | reproduce_and_fix | A message was rejected in production | Explain → validate → triage each finding → refine in place → re-validate → diff → re-send | | seed_validate_monitor | Seeding a UAT environment | Generate an FK-safe cohort (Flock) → validate the batch (Post) → begin monitoring (Loft) |

Each prompt carries a per-workflow free/Pro breakdown (which chained tools are free vs paid) and a one-line freePaidNote — read them in MANIFEST.md or pidgeon://version. The line falls where you'd expect: diagnosis is free, fix-and-deliver is Pro. AI-assisted steps (refine_hl7_segment) default to a bundled on-device model — no API key, no PHI to the cloud; run pidgeon ai download qwen3-4b to set it up. BYOK is optional and never required.

Resources

Static reference data accessible to the AI client:

| URI | Description | |-----|-------------| | pidgeon://hl7/segments | Index of 27 HL7 segment types with descriptions | | pidgeon://hl7/segments/{segmentCode} | Field-level spec for a specific segment (e.g., pidgeon://hl7/segments/PID) | | pidgeon://vendors | Known vendor profiles: Epic, Cerner, Meditech, Allscripts, athenahealth, NextGen, Mirth | | pidgeon://version | Machine-readable self-description: version, mode, resolved tier, the full 18-tool roster with per-tool tier, the prompt catalog with per-workflow tiers, the on-device AI posture, and free-tier volume state | | pidgeon://session | Durable session context (Bridge mode): the active organization/facility scope, saved field-pin sessions, and on-device model status — what an agent reads to orient in the same world the human is working in | | pidgeon://setup-guide | Setup + troubleshooting guide: installation, mode selection, env vars, common issues |

Transport Modes

CLI mode (recommended for most users)

Spawns the pidgeon CLI as a subprocess. Works without any server running.

PIDGEON_MODE=cli

Requires: dotnet tool install -g pidgeon

Bridge mode (full features)

Calls the Pidgeon Bridge REST API. Required for authenticated Pro features.

PIDGEON_MODE=bridge
PIDGEON_BRIDGE_URL=http://localhost:5000

Requires: dotnet run --project pidgeon-cli/src/Pidgeon.Bridge

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | PIDGEON_MODE | bridge | Transport: bridge or cli | | PIDGEON_BRIDGE_URL | http://localhost:5000 | Bridge API base URL (Bridge mode only) | | PIDGEON_API_KEY | (none) | API key for authenticated Bridge instances | | PIDGEON_CLI_PATH | pidgeon | Path to pidgeon CLI executable (CLI mode only) | | PIDGEON_TOOLS | (none) | Optional toolset narrowing: comma-separated tool names or tiers (free, pro) to register. Empty = the full roster (default) | | PIDGEON_EXCLUDE_TOOLS | (none) | Optional toolset narrowing: comma-separated tool names or tiers to withhold, applied after the include list |

Troubleshooting

"CLI not found": Make sure the Pidgeon CLI is on your PATH. Run pidgeon --version from your terminal. If it's not found, install with dotnet tool install -g pidgeon and ensure ~/.dotnet/tools is on your PATH.

"Bridge not reachable": Start the Bridge first (dotnet run --project pidgeon-cli/src/Pidgeon.Bridge), or switch to CLI mode by setting PIDGEON_MODE=cli.

npx hangs or times out: Use -y flag to auto-accept: "args": ["-y", "@pidgeonhealth/mcp"]

Windows path issues: Use forward slashes in PIDGEON_CLI_PATH, or specify the full path: "PIDGEON_CLI_PATH": "C:/Users/you/.dotnet/tools/pidgeon.exe"

Claude Desktop doesn't see the tools: Restart Claude Desktop after editing claude_desktop_config.json. Check the MCP server logs in Claude Desktop settings.

Pro tools show upgrade message: Your tier is detected automatically. If you're a Pro subscriber, make sure you're using Bridge mode with pidgeon auth login completed.

Development

cd pidgeon-mcp
npm install
npm run build     # compile TypeScript
npm test          # smoke + structured-signal + manifest drift guard (47 tests)
npm run manifest  # regenerate manifest.json / MANIFEST.md / bundle/manifest.json
npm run dev       # run with ts-node (no compile step)

License

MPL-2.0 — same as the Pidgeon CLI.