Healthcare Revenue Cycle Management (RCM) Multi-Agent MCP Server

An AI-native multi-agent Revenue Cycle Management (RCM) MCP server implementing Eligibility Verification, Prior Authorization, and a Shared Reasoning Trace backed by Supabase and pgvector.

Architecture Overview

                          ┌────────────────────────────┐
                          │    RCM Multi-Agent System  │
                          │   (Eligibility / PriorAuth)│
                          └─────────────┬──────────────┘
                                        │ (SSE / HTTP / stdio)
                          ┌─────────────▼──────────────┐
                          │   FastMCP Server (Port 8000)│
                          │  trace.* | eligibility.*   │
                          │        priorauth.*         │
                          └─────────────┬──────────────┘
                                        │
                 ┌──────────────────────┴──────────────────────┐
                 ▼                                             ▼
     ┌────────────────────────┐                   ┌────────────────────────┐
     │  Supabase Relational   │                   │  pgvector / Semantic   │
     │  (Payers, Coverage,    │                   │  (Historical Clinical  │
     │   Rules, Traces)       │                   │   Precedents & Cases)  │
     └────────────────────────┘                   └────────────────────────┘

Related MCP server: mymedi-ai-mcp-server

1. Supabase Database Setup

Step 1.1: Create a Supabase Project

1. Log in to Supabase and create a new project.

2. Under Project Settings -> Database, note your Project URL and API Keys (anon or service_role).

Step 1.2: Enable pgvector & Apply Schema

1. Open the SQL Editor in your Supabase Dashboard.

2. Copy and paste the contents of supabase/schema.sql and run it:

   • Enables vector extension (CREATE EXTENSION IF NOT EXISTS vector;).

   • Creates tables: payers, appointments, patient_coverage, benefit_accumulators, payer_pa_rules, pa_requests, agent_trace (append-only), and escalations.

   • Creates the match_pa_cases cosine similarity vector search function.

Step 1.3: Load Seed Data

You can seed synthetic data into Supabase using either option:

Option A (Python Seeder Script): Once you configure .env with your SUPABASE_URL and SUPABASE_KEY:

python seed_data.py

Option B (SQL Editor): In the SQL Editor, copy and paste the contents of supabase/seed.sql and run it.

This seeds:

• 5 Payers: Aetna Commercial, Blue Cross Blue Shield, UnitedHealthcare, Medicare Part B, Cigna.

• 5 Appointments: Scheduled visits with target Dates of Service (DOS).

• Coverage Records: Active vs. terminated policies for edge-case testing.

• Benefit Accumulators: Deductibles, copays, coinsurance for specific CPT codes.

• PA Rules & Precedents: Prior authorization guidelines and historical cases with embeddings.

2. Environment Configuration

Copy .env.example to .env:

cp .env.example .env

Update your .env file with your credentials:

# Supabase Configuration
SUPABASE_URL=https://<your-project-ref>.supabase.co
SUPABASE_KEY=<your-supabase-service-role-or-anon-key>

# Server Configuration
MCP_SERVER_HOST=0.0.0.0
MCP_SERVER_PORT=8000

# Optional Embedding Key
OPENAI_API_KEY=

3. Installation

Install project dependencies:

pip install -r requirements.txt

4. MCP Tools Reference

A. Shared Trace Tools (trace.*)

Used across all agents to maintain an append-only, auditable decision log.

B. Eligibility Tools (eligibility.*)

Verifies patient coverage on the actual appointment Date of Service (DOS) and estimates patient cost.

C. Prior Authorization Tools (priorauth.*)

Automates procedure rule lookup, precedent search, and clinical justification submission.

5. Running the MCP Server

Option A: SSE Transport (Default)

Starts the FastMCP server over Server-Sent Events (SSE):

python run_server.py

• The SSE endpoint will be available at: http://localhost:8000/sse

Option B: Custom Host/Port or Stdio

You can customize transport parameters directly:

# Run over stdio (e.g. for Claude Desktop / CLI clients)
python src/mcp_server/server.py --transport stdio

# Run over SSE on custom port
python src/mcp_server/server.py --transport sse --port 8080

6. Testing & Verification

Run the test suite with pytest:

pytest tests/

Expected output:

tests\test_mcp_tools.py ..........                                       [100%]
============================= 10 passed in 0.07s ==============================

7. Connecting to Agent Clients

Claude Desktop Configuration

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "rcm-server": {
      "command": "python",
      "args": ["<path-to-repo>/src/mcp_server/server.py", "--transport", "stdio"]
    }
  }
}