CUF Health Portal MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@CUF Health Portal MCP Server show my upcoming appointments"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
CUF Health Portal MCP Server
An MCP (Model Context Protocol) server that exposes the CUF health portal as tools for Claude and other MCP clients.
Tools
Tool | Description |
| Patient profile (name, contacts, NIF, SNS number) |
| Upcoming appointments |
| Full appointment history |
| Imaging reports, lab reports, clinical files, etc. |
| Download a clinical document PDF by ID |
| Active lab/exam results from the portal |
| All invoices |
| Download an invoice PDF by payment number |
| Exam prescriptions (scrapes www.cuf.pt) |
| Download a prescription PDF by download URL |
Downloaded PDFs are saved to ./downloads/cuf/ by default (configurable via OUTPUT_DIR env var).
Related MCP server: jcs-mcp
Setup
Requirements
A CUF portal account (saudecuf.pt)
Install
git clone <repo>
cd cuf-mcp
uv syncConfigure credentials
Create a .env file:
CUF_USERNAME=your.email@example.com
CUF_PASSWORD=yourpassword
OUTPUT_DIR=./downloads # optionalRegister with Claude Code
Add to ~/.claude/claude_desktop_config.json (or your MCP settings):
{
"mcpServers": {
"cuf-health": {
"command": "uv",
"args": ["run", "--directory", "/path/to/cuf-mcp", "python", "mcp_server.py"]
}
}
}Then run /mcp in Claude Code to connect.
Run standalone (MCP Inspector)
uv run mcp dev mcp_server.pyBulk download all records
uv run python download_cuf.pyDownloads all clinical documents and invoices to ./downloads/cuf/.
Architecture
Authentication
The portal uses two separate auth systems:
saudecuf.ptGraphQL API — JWT bearer token obtained viaauthenticationMutation. The JWT containspatientId,usercode, andinternalPatientCode. Headers requirex-channel-type-id: 1and a per-requestx-transaction-idUUID.cuf.ptDrupal (prescriptions only) — Separate Drupal session cookie (SSESS*) obtained by POSTing tohttps://www.cuf.pt/mycuf/login. Prescriptions are server-rendered HTML, not available via GraphQL.
Key files
mcp_server.py— FastMCP server; defines all 10 tools; lazy-initializes a shared authenticatedCufClientcuf_client.py— AsyncCufClientclass; wraps all GraphQL queries and the prescription scraperdownload_cuf.py— Standalone bulk downloader script
WAF note
The portal runs behind a Barracuda WAF that blocks headless Chromium. Plain httpx with browser-like headers works fine.
Notes
list_exam_resultscurrently returns an empty list — thegetActiveExamResultsGraphQL endpoint requires a separate auth scope not present in the standard JWT.Prescriptions use
internalPatientCodeas the client identifier, notpatientId.Invoice
paymentNumberformat:"CCF2026/45291"→docSeries="CCF2026",docNumber="45291".
Available Tools
12 toolsget_clinical_documentA
Download a specific clinical document PDF by its ID.
Args: doc_id: The document ID from list_clinical_documents (e.g. "12345").
Returns the file path where the PDF was saved.
Inputs: doc_id (required). Returns: result
get_invoiceA
Download a specific invoice PDF by payment number.
Args: payment_number: The paymentNumber from list_invoices (e.g. "CCF2026/45291" or "FT FSDR2025/170390").
Returns the file path where the PDF was saved.
Inputs: payment_number (required). Returns: result
get_notificationsA
Get patient portal notifications.
Args: include_read: Whether to include already-read notifications (default: True).
Returns a list of dicts with keys: id, name, description, date, message, read, entityType, entityCode.
Inputs: include_read. Returns: result
get_patient_infoA
Get basic patient profile information (name, contacts, identity numbers).
Returns a dict with keys: fullName, title, contacts, identity.
Inputs: no named parameters.
get_prescriptionA
Download a prescription PDF by its download_url from list_prescriptions().
Args: download_url: The download_url field from list_prescriptions() output.
Returns the file path where the PDF was saved.
Inputs: download_url (required). Returns: result
list_appointmentsB
List upcoming and recent appointments.
Args: date_from: ISO date string (YYYY-MM-DD) to start from. Defaults to today.
Returns a list of dicts with keys: id, scheduledDatetime, medicalActName, staffName, siteName, status, type, canCancel, canReSchedule, and more.
Inputs: date_from. Returns: result
list_clinical_documentsA
List all clinical documents (imaging reports, cardiology, pathology, etc.).
Returns a list of dicts with keys: id, patientId, documentType, documentDate, fileName.
Inputs: no named parameters. Returns: result
list_exam_resultsA
List active lab/exam results available in the portal.
Returns a list of dicts with keys: code, report, client. Note: This section may be empty if no results are currently available.
Inputs: no named parameters. Returns: result
list_invoicesA
List all invoices from the CUF portal.
Returns a list of dicts with keys: id, code, paymentNumber, date, status, value, externalSiteCode.
Inputs: no named parameters. Returns: result
list_past_appointmentsA
List all past appointments (from 2000-01-01 to today).
Returns a list of dicts with keys: id, scheduledDatetime, medicalActName, staffName, siteName, status, type, and more.
Inputs: no named parameters. Returns: result
list_prescriptionsA
List exam prescriptions from the CUF portal (www.cuf.pt).
Scrapes the Drupal-rendered HTML page — prescriptions use a separate auth system from the GraphQL API. Returns list of dicts with: date, patient, site, download_url, document_id.
Args: years: List of years to fetch (default: current year and 2 prior years).
Inputs: years. Returns: result
parse_prescriptionA
Parse a downloaded prescription PDF with a local Ollama model.
Extracts text from the PDF and sends it to a local Ollama model for structured extraction. Falls back to vision-mode (image rendering) for image-based PDFs.
Args: file_path: Path to the prescription PDF (from get_prescription). model: Ollama model ID to use (default: "llama3.2"; use a vision model like "llava" if the PDF is image-based).
Returns structured dict with: patient, date, doctor, specialty, medications (list with name/dci/strength/form/quantity/posology/duration), prescription_number, notes.
Inputs: file_path (required), model.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Most tools map cleanly to distinct resource/action pairs, and the list_/get_ pairing makes common document and invoice workflows obvious. However, list_appointments and list_past_appointments clearly overlap for recent past appointments, and list_exam_results vs list_clinical_documents have some potential boundary ambiguity around lab/pathology results. The descriptions help, but a couple of tools could still be confused.
All tool names follow a consistent snake_case verb_noun pattern: list_ for collections, get_ for individual items or PDF downloads, and parse_ for prescription extraction. This makes the tool set highly predictable and easy for an agent to navigate.
12 tools is well-scoped for a health portal covering clinical documents, invoices, appointments, exam results, prescriptions, notifications, and patient info. Each tool has a clear purpose, and none feel redundant or superfluous.
Read-only retrieval is well covered: every listed resource has at least a list/get or download path, and prescription parsing adds useful post-processing. However, appointment fields like canCancel and canReSchedule indicate self-service actions that are not exposed, and there are no cancel/reschedule or update workflow tools. This creates notable dead ends for tasks beyond viewing or downloading.
Related MCP Connectors
Your lab results, DNA files and wearable data explained in your agent, with action plans. EU-hosted.
Your own health records from Vora, Still, Stackwell and Joiva in your AI assistant (OAuth).
Your MedNode health vault in your AI assistant — records, summaries, labs, appointments.
Telehealth support for Claude, Codex and Cursor: investigate cases and connect your tools.
Related MCP Servers
- FlicenseAqualityDmaintenanceEnables AI agents to manage appointments on Medicover's Polish patient portal, including booking, rescheduling, and slot searching for patients and dependents.7-
- FlicenseAqualityDmaintenanceExposes the Joaquim Chaves Saúde patient portal as MCP tools, letting Claude or other clients fetch appointments, prescriptions, invoices, and documents from webapp.jcs.pt.11-
- AlicenseNot gradedqualityCmaintenanceEnables users to read their own Clalit Health Services records—including lab results, prescriptions, lab orders, visit and hospital summaries, and source PDFs—through an AI assistant over MCP or a CLI, with local browser-based sign-in and session keep-alive.MIT
- AlicenseBqualityBmaintenanceEnables AI assistants to read a user's own lab results, imaging reports, visit summaries, and upcoming appointments from the beWell patient portal, with local sign-in and read-only access.6MIT