IFRC GO Server

Read-only MCP server for IFRC GO data, secured with Microsoft Entra ID OAuth/JWT.

What this server does

• Exposes some IFRC GO datasets as MCP tools.
• Enforces bearer-token auth with Entra JWT validation.
• Publishes OAuth metadata endpoints for MCP clients.
• Applies request rate limiting.
• Removes selected PII fields from responses before returning data.
• Adds GO frontend URLs to records so callers can open source pages directly.

Main tools

• get_agent_instructions
  • Returns the full data model and querying guidance from agent-instructions.md.
• get_server_info
  • Returns runtime configuration and upstream connectivity status.
• ifrcgo_meta
  • Returns live enum/choice metadata for entity fields via OPTIONS.
• ifrcgo_read
  • Main read tool for list/detail access across IFRC GO entities.
• ifrcgo_get_country_plan
  • Finds and summarizes the best available planning document for a country.
• ifrcgo_download_document
  • Downloads authenticated IFRC GO documents and extracts text (including PDFs).

Supported entities (via ifrcgo_read)

• Reference: region, country, district, disaster_type
• Events and reports: event, field-report, situation_report
• Appeals: appeal, appeal_document
• Surge and deployments: surge_alert, eru, eru_owner, personnel, partner_deployment
• Projects: project, emergency-project
• Other: public-per-process-status, public-per-stats, ops-learning, public-local-units
• Country detail: country-plan, country-document, country-supporting-partner, delegation_office

See agent-instructions.md for field-level guidance and workflow examples.

Quick start (local)

1. Create and activate a virtual environment

Windows PowerShell:

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

2. Install dependencies

pip install -r requirements.txt

3. Configure environment variables

Set these in your shell, profile, or launch config before starting the server.

Required for auth-gated operation:

• ENTRA_TENANT_ID
• ENTRA_AUDIENCE
• ENTRA_CLIENT_ID
• MCP_SERVER_URL
• STATE_SIGNING_SECRET

IFRC GO upstream auth:

• Static token mode (supported by current server.py):
  • IFRCGO_API_TOKEN

Note: local.settings.json.template and deployment scripts include IFRCGO_USERNAME and IFRCGO_PASSWORD, but the current server process initializes IFRCGOClient with IFRCGO_API_TOKEN only.

Optional:

• IFRCGO_API_BASE_URL (default: https://goadmin.ifrc.org/api/v2)
• ENTRA_REQUIRED_SCOPE (default: mcp.access)
• REQUIRED_GROUP_IDS (comma-separated)
• REQUIRED_APP_ROLES (comma-separated)
• MCP_RATE_LIMIT_REQUESTS (default: 60)
• MCP_RATE_LIMIT_WINDOW_SECONDS (default: 60)
• SCOPE_NAME (default: ifrcgo)
• HOST (default: 0.0.0.0)
• PORT (default: 8000)

4. Run the server

python server.py

Health endpoint:

• GET /health

OAuth metadata endpoints:

• GET /.well-known/oauth-protected-resource
• GET /.well-known/oauth-authorization-server
• GET /.well-known/oauth-authorization-server/mcp

OAuth helper endpoints:

• GET /oauth/authorize
• GET /oauth/callback
• POST /oauth/token
• POST /register

MCP transport:

• Mounted at / using streamable HTTP from FastMCP.
• MCP JSON-RPC calls are available at /mcp.

Testing

Run unit tests:

pytest tests -q -m "not smoke" --ignore=tests/smoke

Run smoke tests (live endpoint + valid token required):

$env:IFRCGO_MCP_URL = "https://<your-host>"
pytest tests/smoke -q -m smoke

Notes:

• Smoke tests require a valid Entra access token. The test fixture in tests/conftest.py defines how this is sourced (az_token).
• The smoke suite calls MCP methods on ${IFRCGO_MCP_URL}/mcp.

Deployment (Azure Container Apps)

This repo includes an automated deploy script:

1. Copy local.settings.json.template to local.settings.json.
2. Fill in required values (subscription, RG, ACR, Entra, IFRC GO credentials, etc.).
3. Run:

bash infra/deploy.sh

On Windows, run the deploy script from a Bash-compatible shell (for example WSL or Git Bash).

What the script handles:

• Validates local settings.
• Runs non-smoke tests before deploy.
• Builds and pushes Docker image.
• Creates/updates Container App and secrets.
• Applies optional ingress IP allow-list.
• Performs health check and optional smoke tests.

Security and privacy notes

• All data tools are read-only.
• OAuth/JWT validation is enforced unless Entra settings are missing.
• If REQUIRED_GROUP_IDS or REQUIRED_APP_ROLES are set, caller token must match at least one.
• Selected PII fields are stripped from personnel and project results.
• Keep local.settings.json and credentials out of source control.

Repository layout

• server.py: MCP server, auth middleware, tool definitions.
• ifrcgo_client.py: Async IFRC GO client, auth refresh, list/detail/options helpers, document parsing.
• agent-instructions.md: Data model and usage guidance surfaced to MCP agents.
• tests/: Unit and smoke tests.
• infra/deploy.sh: Azure deployment automation.
• scripts/: One-off data processing utilities and generated outputs.

Notes for MCP clients

• Start sessions by calling get_agent_instructions.
• Use ifrcgo_meta to resolve current enum values before filtering.
• Use ifrcgo_read with limit and offset for paging.
• Use detail mode with resource_id when you need full single-record payloads.