--- 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: ```env 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: ```python demo.launch(mcp_server=True) ``` ### MCP endpoints When the Space is running, Gradio exposes: - MCP SSE endpoint: `https:///gradio_api/mcp/sse` - MCP schema: `https:///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`: ```jsonc { "mcpServers": { "credentialwatch": { "command": "npx", "args": [ "mcp-remote", "https:///gradio_api/mcp/sse" ] } } } ``` Replace `` with the full URL of your Space. ## Local development ```bash # 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`: ```bash 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.*