AI Agent / MCP Client
          |
          | Model Context Protocol
          v
      /mcp endpoint
          |
          v
       Uvicorn
          |
          v
      Starlette
          |
          v
       FastMCP
          |
   +------+------+------+------+------+
   |      |      |      |      |
   v      v      v      v      v
 Create  Find   Check  Cancel Reschedule
   |      |      |      |      |
   +------+------+------+------+------+
                 |
                 v
            HTTPX Client
                 |
                 | REST API
                 v
        Appointment Backend
         (MockAPI by default)

doctor-appointment-mcp/
├── server.py
├── requirements.txt
├── start.sh
├── run.sh
├── README.md
├── .gitignore
└── .gitattributes

fastmcp>=3.0
uvicorn[standard]>=0.30
httpx>=0.27

git clone https://github.com/josh747jr/doctor-appointment-mcp.git
cd doctor-appointment-mcp

python -m venv .venv
.\.venv\Scripts\Activate.ps1

python3 -m venv .venv
source .venv/bin/activate

pip install -r requirements.txt

$env:APPOINTMENTS_API="https://YOUR-API-ENDPOINT/appointments"

export APPOINTMENTS_API="https://YOUR-API-ENDPOINT/appointments"

python -m uvicorn server:app --host 127.0.0.1 --port 8000

http://127.0.0.1:8000/mcp

http://127.0.0.1:8000/health

ok

{
  "patient_name": "John Doe",
  "doctor_name": "Dr. Mike",
  "appointment_date": "2026-09-18",
  "appointment_time": "2:00 PM",
  "reason": "Annual physical"
}

Schedule an appointment for John Doe with Dr. Mike on September 18, 2026
at 2:00 PM for an annual physical.

{
  "patient_name": "John Doe"
}

{
  "patient_name": "John Doe",
  "doctor_name": "Dr. Mike"
}

{
  "appointment_date": "2026-09-18"
}

{
  "success": true,
  "message": "Found 1 matching appointment(s).",
  "count": 1,
  "appointments": [
    {
      "id": "12",
      "patientName": "John Doe",
      "doctorName": "Dr. Mike",
      "appointmentDate": "2026-09-18",
      "appointmentTime": "2:00 PM",
      "reason": "Annual physical",
      "status": "scheduled"
    }
  ]
}

Find my appointment with Dr. Mike.

What appointments does John Doe have?

Find John Doe's appointment on September 18, 2026.

{
  "appointment_id": "12"
}

What is the status of appointment 12?

{
  "appointment_id": "12"
}

cancelled

Cancel appointment 12.

{
  "appointment_id": "12",
  "new_appointment_date": "2026-09-21",
  "new_appointment_time": "10:00 AM"
}

Move appointment 12 to September 21, 2026 at 10:00 AM.

{
  "id": "12",
  "patientName": "John Doe",
  "doctorName": "Dr. Mike",
  "appointmentDate": "2026-09-18",
  "appointmentTime": "2:00 PM",
  "reason": "Annual physical",
  "status": "scheduled"
}

POST /appointments
GET  /appointments
GET  /appointments/{id}
PUT  /appointments/{id}

patientName
doctorName
appointmentDate

Find my appointment with Dr. Mike.

find_appointments(patient_name="John Doe", doctor_name="Dr. Mike")

Move that appointment to September 21 at 10 AM.

reschedule_appointment(
    appointment_id="12",
    new_appointment_date="2026-09-21",
    new_appointment_time="10:00 AM"
)

$env:MCP_REQUEST_HEADERS="my-secret"

export MCP_REQUEST_HEADERS="my-secret"

MCP_REQUEST_HEADERS

export MCP_REQUEST_HEADERS='{"X-API-Key":"my-secret"}'

X-API-Key: my-secret

start.sh
run.sh

APPOINTMENTS_API=https://YOUR-API-ENDPOINT/appointments

MCP_REQUEST_HEADERS=your-secret

https://YOUR-SERVER/mcp

https://YOUR-SERVER/health

python -m uvicorn server:app --host 127.0.0.1 --port 8000

curl http://127.0.0.1:8000/health

ok

http://127.0.0.1:8000/mcp

create_appointment
find_appointments
check_appointment_status
cancel_appointment
reschedule_appointment