Northstar Clinic MCP Apps demo

This branch extends the existing appointment application with text-first MCP tools and an interactive MCP App that compatible hosts such as Claude Desktop can render inside the conversation.

The teaching demo uses an in-memory AppointmentStore so it can be reset instantly. In a production application, this module would be replaced by a database-backed repository without changing the browser-to-API contract.

Run it

Start the clinic API and keep it running:

uv sync
uv run uvicorn clinic_api:app --host 127.0.0.1 --port 8765
uv run uvicorn clinic_api:app --host 127.0.0.1 --port 8765

The browser version is at http://127.0.0.1:8765. API docs are at http://127.0.0.1:8765/docs.

Architecture

• clinic_browser.html is the browser UI.
• clinic_api.py exposes appointment and booking HTTP endpoints.
• clinic_store.py owns availability and atomic booking state.
• clinic_mcp.py adapts those HTTP capabilities into MCP tools and exposes the widget resource.
• clinic_widget.html is the interactive UI rendered by the MCP host. It calls MCP tools through the MCP Apps SDK; it does not bypass the MCP server to call FastAPI directly.

Claude Desktop starts clinic_mcp.py as a local stdio MCP server. After changing the MCP server or widget, fully quit and reopen Claude Desktop so it reconnects and reloads the resource.

Configure the MCP server from Claude Desktop

1. Open the Claude Desktop app.
2. Press Command + , to open Settings.
3. In the settings sidebar, find Desktop app and select Developer.
4. Under Local MCP servers, click Edit Config. Claude opens its claude_desktop_config.json file in the default editor.
5. Add the northstar-clinic entry under mcpServers:

{
  "mcpServers": {
    "northstar-clinic": {
      "command": "/Users/yashpatil/.local/bin/uv",
      "args": [
        "run",
        "--directory",
        "/Users/yashpatil/Developer/AI/mcp_apps",
        "python",
        "clinic_mcp.py"
      ],
      "env": {
        "CLINIC_API_URL": "http://127.0.0.1:8765"
      }
    }
  }
}

If the file already contains other MCP servers, add northstar-clinic inside the existing mcpServers object instead of replacing the entire file.

Save the file, fully quit Claude Desktop with Command + Q, and reopen it. Return to Settings → Desktop app → Developer and confirm that northstar-clinic appears under Local MCP servers with a running status.

The FastAPI backend must be running separately before using the MCP tools:

uv run uvicorn clinic_api:app --host 127.0.0.1 --port 8765

Rehearsed demo

1. Ask: Use Northstar Clinic to find all available appointments and show the interactive dashboard.
2. Filter to Dermatology in the rendered widget.
3. Click Book visit and review the appointment.
4. Enter the required contact number and reason, then click Confirm appointment.
5. Show that the appointment disappears from availability and that the receipt contains its reference.
6. Verify the same change with GET /api/appointments or the browser frontend.

Branch-based lesson

git switch main           # existing FastAPI + browser application
git switch codex/mcp-app  # MCP server + Claude-rendered widget
git diff main..codex/mcp-app

Quick checks

curl http://127.0.0.1:8765/health
curl http://127.0.0.1:8765/api/appointments

The API is intentionally in-memory. Restarting it restores the six seeded slots.