README.md

metadata

title: CredentialWatch MCP Server
emoji: 🩺
colorFrom: blue
colorTo: purple
sdk: gradio
python_version: 3.11
sdk_version: 6.0.1
app_file: app.py
fullWidth: true
short_description: Gradio MCP server exposing healthcare credential tools.
tags:
  - mcp
  - gradio
  - tools
  - healthcare
pinned: false

CredentialWatch MCP Server

CredentialWatch is a proactive healthcare credential management system built for the Hugging Face MCP 1st Birthday / Gradio Agents Hackathon. It leverages the Model Context Protocol (MCP), LangGraph agents, Gradio, and Modal to unify fragmented credential data and alert on upcoming expiries.

Hugging Face Space

This repository is designed to run as a Gradio Space.

• SDK: Gradio (sdk: gradio in the README header)
• Entry file: app.py (set via app_file in the YAML header)
• Python: 3.11+ (pinned with python_version)

When you push this repo to a Space with SDK = Gradio, the UI and the MCP server will be started automatically.

Configuration

The server requires the backend Credential API URL to be configured. In your Space settings (or local .env file), add:

CRED_API_BASE_URL=http://localhost:8000  # Replace with actual backend URL

MCP Server

This Space exposes its tools via Model Context Protocol (MCP) using Gradio.

How MCP is enabled

In app.py we:

• install Gradio with MCP support: pip install "gradio[mcp]"
• define typed Python functions with docstrings
• launch the app with MCP support:

demo.launch(mcp_server=True)

MCP endpoints

When the Space is running, Gradio exposes:

• MCP SSE endpoint: https://<space-host>/gradio_api/mcp/sse
• MCP schema: https://<space-host>/gradio_api/mcp/schema

Using this Space from an MCP client

Easiest: Hugging Face MCP Server (no manual config)

1. Go to your HF MCP settings: https://huggingface.co/settings/mcp
2. Add this Space under Spaces Tools (look for the MCP badge on the Space).
3. Restart your MCP client (VS Code, Cursor, Claude Code, etc.).
4. The tools from this Space will appear as MCP tools and can be called directly.

Manual config (generic MCP client using mcp-remote)

If your MCP client uses a JSON config, you can point it to the SSE endpoint via mcp-remote:

{
  "mcpServers": {
    "credentialwatch": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://<space-host>/gradio_api/mcp/sse"
      ]
    }
  }
}

Replace <space-host> with the full URL of your Space.

Local development

# 1. Install deps
uv sync
# or
pip install -r requirements.txt

# 2. Run locally
uv run python app.py

The local server will be available at http://127.0.0.1:7860, and MCP at http://127.0.0.1:7860/gradio_api/mcp/sse.

Deploying to Hugging Face Spaces

1. Create a new Space with SDK = Gradio.
2. Push this repo to the Space (Git or huggingface_hub).
3. Ensure the YAML header in README.md is present and correct.
4. Wait for the Space to build and start — it should show an MCP badge automatically.

Troubleshooting

• Configuration error: Verify sdk, app_file, and python_version in the YAML header. The header must be the first thing in the file (no blank lines before ---).
• MCP badge missing: Check that your app calls demo.launch(mcp_server=True) and confirm the Space is public.
• LFS issues: Ensure README.md is NOT tracked via Git LFS.

---

🎯 Project Goal

CredentialWatch transforms messy, decentralized provider data (state licenses, board certifications, DEA numbers) into:

1. A unified, queryable source of truth.
2. A proactive alerting system for at-risk credentials.

The system is designed to solve the real-world problem of missed credential expiries leading to compliance issues, denied claims, and scheduling conflicts.

🧩 Architecture

The system follows a microservice-like architecture with strict separation of concerns, orchestrated by a LangGraph agent.

Components

1. Agent UI (Gradio + LangGraph): The user interface where users interact with the agent (chat or sweep triggers).
2. Three MCP Servers:
   • npi_mcp: Read-only access to the public NPPES NPI Registry.
   • cred_db_mcp: (Hosted in this repo) Internal provider & credential database operations.
   • alert_mcp: Alert logging and resolution management.
3. Modal Backend: Hosting FastAPI microservices and the SQLite database (credentialwatch.db).

Data Flow

User <-> Gradio UI <-> LangGraph Agent
                            |
           -----------------------------------
           |                |                |
      [npi_mcp]      [cred_db_mcp]     [alert_mcp]
           |                |                |
      (NPI_API)        (CRED_API)       (ALERT_API)
           |                |                |
        NPPES         [SQLite DB]      [SQLite DB]

📂 Repository Contents: cred_db_mcp_server

This repository currently hosts the Credential Database MCP Server (cred_db_mcp). This component provides the tools necessary for the agent to read from and write to the internal provider/credential database.

Exposed Tools

The server exposes the following MCP tools (via Gradio's MCP support):

• sync_provider_from_npi(npi):
  • Syncs a provider's data from the NPI registry (via backend) to the local database.
  • Usage: Onboarding new providers.
• add_or_update_credential(provider_id, type, issuer, number, expiry_date):
  • Upserts a credential record for a provider.
  • Usage: Keeping license data current.
• list_expiring_credentials(window_days, dept?, location?):
  • Returns a list of credentials expiring within the specified window (e.g., 90 days).
  • Usage: Proactive monitoring and sweeps.
• get_provider_snapshot(provider_id?, npi?):
  • Returns provider info + all credentials + alerts.
  • Usage: Context retrieval for user queries.

🧪 Testing

Run the unit tests using pytest:

uv run pytest

🛠 Tech Stack

• Python 3.11
• Gradio 5+ (Frontend & MCP Server)
• FastAPI / HTTPX (Networking)
• Pydantic (Data validation)
• uv (Package management)

---

Built for the Hugging Face MCP 1st Birthday Hackathon.