IFRC GO MCP 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.

Related MCP server: FoxTrove Voice MCP Server

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

• DREF: active-dref, completed-dref, dref-op-update, dref-final-report

• Other: flash-update, 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 (choose one mode):

• Recommended auto-refresh mode:

  • IFRCGO_USERNAME

  • IFRCGO_PASSWORD

• Static token mode:

  • IFRCGO_API_TOKEN

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.

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>"
$env:MCP_TEST_TOKEN = "<entra-access-token>"
pytest tests/smoke -q -m smoke

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

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.