README.md

metadata

title: CredentialWatch MCP Server
emoji: 🩺
colorFrom: blue
colorTo: purple
sdk: gradio
python_version: 3.11
sdk_version: 6.0.0
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

Agent-ready Gradio Space that exposes healthcare credential tools (lookups, expiry checks, risk scoring) over Model Context Protocol (MCP).

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.

🩺 About CredentialWatch

CredentialWatch is an agentic system designed to manage healthcare provider credentials. It serves as a central radar to track expiries, license statuses, and compliance risks across multiple providers.

Role of npi_mcp

This MCP server exposes tools to search for and retrieve healthcare provider information from the public NPPES NPI Registry. It acts as a proxy, forwarding requests to a backend Modal FastAPI service (NPI_API) which handles the actual external API communication and normalization.

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

✨ Tools

This server exposes the following MCP tools:

• search_providers(query, state?, taxonomy?):
  • Search for providers by name, organization, state, or taxonomy.
  • Returns a list of matching providers with summaries.
• get_provider_by_npi(npi):
  • Retrieve detailed information for a specific provider using their 10-digit NPI number.

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 pip install "gradio[mcp]" -r requirements.txt

# 2. Run locally
uv run python app.py
# or
GRADIO_MCP_SERVER=True 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.

Testing

Run tests using pytest:

uv run pytest

Note: The server requires the URL of the backend Modal service. Set the following environment variable:

export NPI_API_BASE_URL="https://your-modal-app-url.modal.run"

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. Go to Settings in your Space and add NPI_API_BASE_URL as a secret or variable if you have a private backend, or ensure the default works.
5. 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.
• MCP badge missing: Check that app.py calls demo.launch(mcp_server=True) or GRADIO_MCP_SERVER=True is set. Confirm the Space is public.
• Tools not working: Ensure NPI_API_BASE_URL is correctly set in the environment.

🏗️ Architecture

• Stack: Python 3.11, mcp, httpx, pydantic.
• Transport: HTTP (to Modal backend), stdio/SSE (to MCP Client).

📄 License

This project is part of a hackathon submission.