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

Downloaded PDFs are saved to ./downloads/cuf/ by default (configurable via OUTPUT_DIR env var).

Related MCP server: MCP NIF.PT

Setup

Requirements

• uv

• A CUF portal account (saudecuf.pt)

Install

git clone <repo>
cd cuf-mcp
uv sync

Configure credentials

Create a .env file:

CUF_USERNAME=your.email@example.com
CUF_PASSWORD=yourpassword
OUTPUT_DIR=./downloads   # optional

Register 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.py

Bulk download all records

uv run python download_cuf.py

Downloads all clinical documents and invoices to ./downloads/cuf/.

Architecture

Authentication

The portal uses two separate auth systems:

• saudecuf.pt GraphQL API — JWT bearer token obtained via authenticationMutation. The JWT contains patientId, usercode, and internalPatientCode. Headers require x-channel-type-id: 1 and a per-request x-transaction-id UUID.

• cuf.pt Drupal (prescriptions only) — Separate Drupal session cookie (SSESS*) obtained by POSTing to https://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 authenticated CufClient

• cuf_client.py — Async CufClient class; wraps all GraphQL queries and the prescription scraper

• download_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_results currently returns an empty list — the getActiveExamResults GraphQL endpoint requires a separate auth scope not present in the standard JWT.

• Prescriptions use internalPatientCode as the client identifier, not patientId.

• Invoice paymentNumber format: "CCF2026/45291" → docSeries="CCF2026", docNumber="45291".