Fayda MCP Python Library (fayda-mcp)

An importable, headless Python library providing Model Context Protocol (MCP) tools and verification services for Ethiopian National ID (Fayda eSignet).

Key Capabilities

• Explicit FastMCP Tools: start_verification, get_verification_status, get_verification_result, cancel_verification.
• Zero Raw Demographic / Biometric Leaks: Outputs minimal boolean predicates (identity_verified, age_over_18), strictly forbidding citizen biometrics, OTPs, or demographic dumps from entering LLM contexts.
• Cryptographic Security: OIDC PKCE S256, RFC 7523 private_key_jwt client assertions, and strict JWT signature/nonce validation.
• Pluggable Architecture: Zero mandatory database or web framework runtime dependencies in core; optional extras for FastAPI, Redis, and Neon/PostgreSQL.
• Multi-Tenant Caller Isolation: Built-in tenant and principal boundaries ensuring Caller A cannot access Caller B verification records.

Installation

# Core library (headless FastMCP + Fayda OIDC verification engine)
pip install fayda-mcp

# With optional FastAPI integration
pip install "fayda-mcp[fastapi]"

# Full bundle with Redis and Neon/Postgres adapters
pip install "fayda-mcp[fastapi,redis,postgres]"

Quick Start (Sandbox)

from fayda_mcp import FaydaConfig, FaydaVerificationService
from fayda_mcp.storage.memory import MemorySessionStore, MemoryResultRepository
from fayda_mcp.mcp.factory import create_mcp_server

# 1. Configure with official Fayda sandbox preset
config = FaydaConfig.sandbox(
    client_id="your_registered_client_id",
    redirect_uri="http://localhost:8000/auth/fayda/callback",
)

# 2. Initialize verification service
service = FaydaVerificationService(
    config=config,
    sessions=MemorySessionStore(),
    results=MemoryResultRepository(),
)

# 3. Create FastMCP server
server = create_mcp_server(service=service)

# 4. Run over stdio (e.g. for Claude Desktop or Cursor)
server.run(transport="stdio")

Running the Complete Sandbox Flow

Run the included standalone sandbox walkthrough:

python examples/sandbox_flow.py

This runs the entire end-to-end lifecycle (starts verification -> builds authorization link -> simulates citizen callback -> queries status -> retrieves privacy-preserving boolean result -> verifies caller isolation) without editing library internals.

Examples

• Local Standard I/O (stdio): examples/stdio_server.py (Desktop LLM clients, Claude Desktop, Cursor)
• Remote HTTP Server: examples/remote_http_server.py (Hosted streamable-HTTP / SSE MCP endpoints with FastAPI)
• Full Sandbox Walkthrough: examples/sandbox_flow.py

Documentation

• Architecture & Responsibilities
• Configuration Guide & Environment Variables
• Callback Wiring & Session Binding
• Credential Ownership & Cryptography
• Cleanup & Lifecycle Management

License

MIT License. See LICENSE for details.