metadata

title: MedCodeMCP
emoji: 💬
colorFrom: yellow
colorTo: purple
sdk: gradio
sdk_version: 5.33.0
app_file: app.py
pinned: false
license: apache-2.0
short_description: an MCP Tool for Symptom-to-ICD Diagnosis Mapping.
tags:
  - mcp-server-track
  - medical-ai
  - diagnostic-assistant
  - icd10
  - speech-recognition
  - multimodal
  - agentic-ai
  - llamaindex-integration
  - gradio-app
  - sambanova-cloud
  - fast-inference
  - custom-components
  - healthcare
  - reusability
  - ui-polish

A voice-enabled medical assistant that takes patient audio complaints, engages in follow-up questions, and returns structured ICD-10 diagnosis suggestions via an MCP endpoint.

Features

Automatic speech recognition (ASR): Transcribe real-time patient audio using Gradio.
Interactive Q&A Agent: The LLM dynamically asks clarifying questions base on ICD codes until it can diagnose with high confidence.
Multi-backend LLM: Switch between OpenAI GPT, Mistral (HF), or a local transformers model via environment flags.
ICD-10 Mapping: Use LlamaIndex for vector retrieval of probable ICD-10 codes with confidence scores.
MCP-Server Ready: Exposes a /mcp REST endpoint for seamless agent integration.

Getting Started

My submission for this hackathon is posted at the following Hugging Face Space: https://huggingface.co/spaces/Agents-MCP-Hackathon/MedCodeMCP

Note that I am also backing up my code to my personal space in case the hackathon space is ever removed: https://huggingface.co/spaces/gpaasch/Grahams_Gradio_Agents_MCP_Hackathon_2025_Submission

Clone & Install

git clone https://huggingface.co/spaces/Agents-MCP-Hackathon/MedCodeMCP
cd MedCodeMCP
python3 -m venv .venv && source .venv/bin/activate  
pip install -r requirements.txt

Environment Variables

Name	Description	Default
`OPENAI_API_KEY`	OpenAI API key for GPT calls	required
`HUGGINGFACEHUB_API_TOKEN`	HF token for Mistral/inference models	required for Mistral
`USE_LOCAL_GPU`	Set to `1` to use a local transformers model (no credits)	`0`
`LOCAL_MODEL`	Path or HF ID of local model (e.g. `distilgpt2`)	`gpt2`
`USE_MISTRAL`	Set to `1` to use Mistral via HF instead of OpenAI	`0`
`MISTRAL_MODEL`	HF ID for Mistral model (`mistral-small/medium/large`)	`mistral-large`
`MISTRAL_TEMPERATURE`	Sampling temperature for Mistral	`0.7`
`MISTRAL_MAX_INPUT`	Max tokens for input prompt	`4096`
`MISTRAL_NUM_OUTPUT`	Max tokens to generate	`512`

Launch Locally

# Default (OpenAI)
python app.py

# Mistral backend
export USE_MISTRAL=1
export HUGGINGFACEHUB_API_TOKEN="hf_..."
python app.py

# Local GPU (no credits)
export USE_LOCAL_GPU=1
export LOCAL_MODEL="./models/distilgpt2"
python app.py

Open http://localhost:7860 to interact with the app.

MCP API Usage

curl -X POST http://localhost:7860/mcp \
  -H "Content-Type: application/json" \
  -d '{"tool":"transcribe_and_respond","input":{"audio":"<base64_audio>","history":[]}}'

Project Structure

├── app.py                      # HF entrypoint
├── src/app.py                  # Core Gradio & agent logic
├── utils/llama_index_utils.py  # LLM predictor & indexing utils
├── data/icd10cm_tabular_2025/  # ICD-10 dataset
├── requirements.txt            # Dependencies
└── README.md                   # This file

Hackathon Timeline

Here are the key dates for the Gradio Agents & MCP Hackathon:

May 20 – 26, 2025: Pre-Hackathon announcements period.
June 2 – 10, 2025: Official hackathon window (sign-ups remain open).
June 3, 2025 — 9 AM PST / 4 PM UTC: Live kickoff YouTube event.
June 4 – 5, 2025: Gradio Office Hours with MCP Support, MistralAI, LlamaIndex, Custom Components team, and Sambanova.
June 10, 2025 — 11:59 PM UTC: Final submission deadline.
June 11 – 16, 2025: Judging period.
June 17, 2025: Winners announced.

Key Players

Panel of Judges

Judging will be conducted by representatives from sponsor partners and the Hugging Face community team, including Modal Labs, MistralAI, LlamaIndex, Sambanova.AI, and Hugging Face. To be properly judged, ensure the project is in the proper space on hugging face, not just in a personal space. Click join organization, then click new to create a space that will be judged.

Office Hours Hosts

Abubakar Abid (MCP Support) — @abidlabs
MistralAI Office Hours — Watch on YouTube
LlamaIndex Office Hours — Watch on YouTube
Custom Components Office Hours — Watch on YouTube
Sambanova Office Hours — Watch on YouTube

Primary Organizers

Yuvraj Sharma (Yuvi) (@yvrjsharma) — Machine Learning Engineer & Developer Advocate, Gradio Team at Hugging Face
Abubakar Abid (@abidlabs) — Developer Advocate & MCP Support Lead at Hugging Face
Gradio Team at Hugging Face — Core organizing team providing platform infrastructure, logistics, and community coordination

Resources

Hackathon Org & Registration: Agents-MCP-Hackathon
Discord: discord.gg/agents-mcp-hackathon
Slides from Kickoff: PDF
Code of Conduct: Contributor Covenant
Submission Guidelines: See “Submission Guidelines” on the hackathon page
MCP Guide: How to Build an MCP Server
Gradio Docs: https://www.gradio.app/docs
LlamaIndex Docs: https://llamaindex.ai/docs
Mistral Model Hub: https://huggingface.co/mistral-ai/mistral-small

Free Credits!

Modal Labs Compute Credits ($250 per participant) Monitor your GPU/CPU credit usage by logging into your Modal account and navigating to Dashboard → Billing: https://modal.com/dashboard (huggingface.co, modal.com)

Hugging Face API Credits ($25 per participant) View your remaining credits and invoices on the Hugging Face billing dashboard: https://huggingface.co/settings/billing (huggingface.co, huggingface.co)

Nebius AI Cloud Credits ($25 to first 3,300 participants) Check your Nebius “Grants and promocodes” balance and detailed billing reports at: https://nebius.com/services/billing (huggingface.co, nebius.com)

Anthropic Claude API Credits ($25 to first 1,000 participants) Track your Claude usage and remaining credits in the Anthropic Console under Settings → Billing: https://console.anthropic.com/settings/billing (huggingface.co)

OpenAI API Credits ($25 to first 1,000 participants) Monitor your API calls, token usage, and spend on the OpenAI Usage dashboard: https://platform.openai.com/account/usage (huggingface.co, platform.openai.com)

Hyperbolic Labs API Credits ($15 to first 1,000 participants) After logging in at the Hyperbolic AI Dashboard, go to Settings → Billing to view your credit balance and transaction history: https://app.hyperbolic.xyz (huggingface.co, docs.hyperbolic.xyz, hyperbolic.xyz)

Mistral AI API Credits ($25 to first 500 participants) Sign in at the Mistral Console and navigate to Workspace → Billing to activate and monitor your credits: https://console.mistral.ai (huggingface.co, docs.mistral.ai)

SambaNova AI Cloud Credits ($25 to first 250 participants) Log in to SambaNova Cloud and check your Billing & Usage in the plans section: https://cloud.sambanova.ai/plans/billing (huggingface.co, cloud.sambanova.ai)

About the Author

Graham Paasch is an AI realist passionate about the coming AI revolution.

LinkedIn: https://www.linkedin.com/in/grahampaasch/
YouTube: https://www.youtube.com/channel/UCg3oUjrSYcqsL9rGk1g_lPQ

Graham is currently looking for work. Inspired by Leopold Aschenbrenner’s “AI Situational Awareness” (https://situational-awareness.ai/), he believes AI will become a multi-trillion-dollar industry over the next decade—what we’re seeing now is the equivalent of ARPANET in the early days of the internet. He’s committed to aligning his work with this vision to stay at the forefront of the AI revolution.

Spaces:

Agents-MCP-Hackathon
/

MedCodeMCP

Running