fayda-mcp 0.1.0__tar.gz

fayda_mcp-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+.env
+.venv/
+__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+dist/
+build/
+scratch*

fayda_mcp-0.1.0/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Copyright 2026 Fayda MCP Contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

fayda_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.5
+Name: fayda-mcp
+Version: 0.1.0
+Summary: Fayda eSignet identity verification tools for Model Context Protocol (MCP)
+License: Apache-2.0
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: cryptography>=43.0.0
+Requires-Dist: fastmcp>=4.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic-settings>=2.5.0
+Requires-Dist: pydantic>=2.9.0
+Requires-Dist: pyjwt>=2.9.0
+Provides-Extra: all
+Requires-Dist: fastapi>=0.115.0; extra == 'all'
+Requires-Dist: greenlet>=3.0.0; extra == 'all'
+Requires-Dist: psycopg[binary]>=3.2.0; extra == 'all'
+Requires-Dist: redis>=5.0.0; extra == 'all'
+Requires-Dist: sqlalchemy[asyncio]>=2.0.0; extra == 'all'
+Requires-Dist: uvicorn[standard]>=0.30.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.115.0; extra == 'dev'
+Requires-Dist: greenlet>=3.0.0; extra == 'dev'
+Requires-Dist: psycopg[binary]>=3.2.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: redis>=5.0.0; extra == 'dev'
+Requires-Dist: sqlalchemy[asyncio]>=2.0.0; extra == 'dev'
+Requires-Dist: uvicorn[standard]>=0.30.0; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.115.0; extra == 'fastapi'
+Requires-Dist: uvicorn[standard]>=0.30.0; extra == 'fastapi'
+Provides-Extra: postgres
+Requires-Dist: greenlet>=3.0.0; extra == 'postgres'
+Requires-Dist: psycopg[binary]>=3.2.0; extra == 'postgres'
+Requires-Dist: sqlalchemy[asyncio]>=2.0.0; extra == 'postgres'
+Provides-Extra: redis
+Requires-Dist: redis>=5.0.0; extra == 'redis'
+Description-Content-Type: text/markdown
+
+# Fayda MCP Python Library (`fayda-mcp`)
+
+[![PyPI version](https://img.shields.io/badge/version-0.1.0-blue.svg)](https://pypi.org/project/fayda-mcp/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+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
+
+```bash
+# 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)
+
+```python
+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:
+
+```bash
+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](examples/stdio_server.py) (Desktop LLM clients, Claude Desktop, Cursor)
+- **Remote HTTP Server**: [examples/remote_http_server.py](examples/remote_http_server.py) (Hosted streamable-HTTP / SSE MCP endpoints with FastAPI)
+- **Full Sandbox Walkthrough**: [examples/sandbox_flow.py](examples/sandbox_flow.py)
+
+---
+
+## Documentation
+
+- [Architecture & Responsibilities](docs/architecture.md)
+- [Configuration Guide & Environment Variables](docs/configuration.md)
+- [Callback Wiring & Session Binding](docs/callback_wiring.md)
+- [Credential Ownership & Cryptography](docs/credentials.md)
+- [Cleanup & Lifecycle Management](docs/cleanup_and_lifecycle.md)
+
+---
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

fayda_mcp-0.1.0/README.md

@@ -0,0 +1,94 @@
+# Fayda MCP Python Library (`fayda-mcp`)
+
+[![PyPI version](https://img.shields.io/badge/version-0.1.0-blue.svg)](https://pypi.org/project/fayda-mcp/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+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
+
+```bash
+# 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)
+
+```python
+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:
+
+```bash
+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](examples/stdio_server.py) (Desktop LLM clients, Claude Desktop, Cursor)
+- **Remote HTTP Server**: [examples/remote_http_server.py](examples/remote_http_server.py) (Hosted streamable-HTTP / SSE MCP endpoints with FastAPI)
+- **Full Sandbox Walkthrough**: [examples/sandbox_flow.py](examples/sandbox_flow.py)
+
+---
+
+## Documentation
+
+- [Architecture & Responsibilities](docs/architecture.md)
+- [Configuration Guide & Environment Variables](docs/configuration.md)
+- [Callback Wiring & Session Binding](docs/callback_wiring.md)
+- [Credential Ownership & Cryptography](docs/credentials.md)
+- [Cleanup & Lifecycle Management](docs/cleanup_and_lifecycle.md)
+
+---
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

fayda_mcp-0.1.0/docs/architecture.md

@@ -0,0 +1,22 @@
+# Fayda MCP Architecture
+
+## Delivery Model
+
+`fayda-mcp` is an importable, headless Python library providing:
+1. Typed FastMCP tools and schemas (`start_verification`, `get_verification_status`, `get_verification_result`, `cancel_verification`).
+2. OIDC PKCE generation and private_key_jwt client assertion support.
+3. Cryptographic JWT and JWKS validation for Fayda eSignet.
+4. Pluggable storage protocols for sessions, results, and audit trails.
+
+## Responsibilities
+
+| Component | Owner |
+|---|---|
+| Typed MCP tools & schemas | `fayda-mcp` library |
+| OIDC / PKCE & client assertions | `fayda-mcp` library |
+| JWT validation & claim evaluation | `fayda-mcp` library |
+| Storage protocols & memory adapter | `fayda-mcp` library |
+| MCP hosting & OAuth transport security | Integrating application |
+| Fayda RP registration & private key | Integrating application |
+| Browser redirect & callback endpoints | Integrating application |
+| Redis / Neon infrastructure | Integrating application |

fayda_mcp-0.1.0/docs/callback_wiring.md

@@ -0,0 +1,65 @@
+# Callback Wiring & Session Binding
+
+In the Fayda eSignet OpenID Connect flow, citizens authorize in their web browser and are redirected back to the host application's registered `redirect_uri`.
+
+## Why Host Session Binding is Required
+
+Without session binding, an attacker could initiate an identity verification flow and trick a victim into completing it, or hijack another user's verification state (CSRF / session injection).
+
+`fayda-mcp` requires a **host session-binding hook** to ensure:
+1. When verification is started, the caller context records a secure browser binding identifier (e.g. `session_id`, cookie HMAC, or authenticated user reference).
+2. When the user returns from Fayda eSignet to `/callback`, the callback router invokes the host hook to extract the browser identifier from the HTTP request.
+3. If the returned session does not match the bound identifier, the callback is rejected with `InvalidStateError`.
+
+---
+
+## FastAPI Integration
+
+Use `create_callback_router` to mount the callback handler on your FastAPI app:
+
+```python
+from fastapi import FastAPI, Request
+from fastapi.responses import RedirectResponse
+from fayda_mcp.integrations.fastapi import create_callback_router
+
+app = FastAPI()
+
+# 1. Define host session-binding hook
+def resolve_browser_session(request: Request) -> str | None:
+    # Extracts the host session cookie from incoming citizen request
+    return request.cookies.get("app_session_id")
+
+# 2. Define on_success redirect hook
+async def on_verification_complete(request: Request, result) -> RedirectResponse:
+    # Redirect citizen to host onboarding completion screen
+    return RedirectResponse(
+        url=f"/onboarding/complete?request_id={result.request_id}&status={result.status}",
+        status_code=303,
+    )
+
+# 3. Mount callback router
+router = create_callback_router(
+    service=service,
+    session_binding_hook=resolve_browser_session,
+    on_success=on_verification_complete,
+)
+
+app.include_router(router)
+```
+
+---
+
+## Registered Redirect URI Alignment
+
+By default, `create_callback_router` inspects `service.config.redirect_uri` to determine the exact path to mount:
+- If `redirect_uri="https://my-app.example/auth/fayda/callback"`, the router mounts on `/auth/fayda/callback`.
+- If `redirect_uri="http://localhost:8000/callback"`, the router mounts on `/callback`.
+
+You can also pass explicit `prefix` and `callback_path` arguments if you mount behind reverse proxies or API gateways.
+
+---
+
+## Error Handling
+
+When Fayda returns an error (such as a citizen canceling consent), Fayda redirects with query parameters `?error=access_denied&error_description=...`.
+The router automatically parses provider errors and passes them to `on_error` if configured, or returns an HTTP 400 Bad Request JSON response.

fayda_mcp-0.1.0/docs/cleanup_and_lifecycle.md

@@ -0,0 +1,56 @@
+# Cleanup & Lifecycle Management
+
+Managing background connections, cached tokens, and short-lived session states properly ensures high security and prevents memory or connection leaks.
+
+---
+
+## 1. Service Lifecycle Management
+
+`FaydaVerificationService` manages an underlying HTTP client pool (`httpx.AsyncClient`) and JWKS cache. Always manage its lifecycle using one of the following patterns:
+
+### Async Context Manager (Recommended for scripts & tests)
+
+```python
+async with FaydaVerificationService(config, sessions, results) as service:
+    # Service connections are active
+    ...
+# Cleanly closed upon block exit (service.aclose() executed)
+```
+
+### Combined FastAPI/FastMCP Lifespan (Recommended for servers)
+
+```python
+from fayda_mcp.integrations.fastapi import create_combined_lifespan
+
+lifespan = create_combined_lifespan(
+    service=service,
+    mcp_server=mcp_server,
+)
+
+app = FastAPI(lifespan=lifespan)
+```
+Using `create_combined_lifespan` guarantees:
+1. `service` HTTP pools and caches start first.
+2. `mcp_server` and host application start up cleanly.
+3. Upon SIGTERM or shutdown, all components are gracefully closed in reverse order.
+
+---
+
+## 2. Session and Result Expiry (TTLs)
+
+To prevent unbounded storage growth and eliminate stale cryptographic state, `fayda-mcp` enforces bounded TTLs on all stored data:
+
+| Setting | Default | Purpose |
+|---|---|---|
+| `session_ttl_seconds` | 600s (10 min) | Lifetime of pending authorization state, nonce, and PKCE verifier |
+| `result_ttl_seconds` | 900s (15 min) | Lifetime of completed minimal verification result |
+| `jwks_cache_ttl_seconds` | 300s (5 min) | Cached Fayda public keys |
+
+### Storage Adapter Behaviors
+
+- **In-Memory Adapter (`MemorySessionStore`, `MemoryResultRepository`)**:
+  Automatically prunes expired entries on access and lookup.
+- **Redis Adapter**:
+  Applies native Redis `EXPIRE` commands matching the configured TTL.
+- **Postgres / Neon Adapter**:
+  Stores `expires_at` ISO timestamps. An index on `expires_at` enables efficient scheduled cleanup jobs (e.g. `DELETE FROM fayda_sessions WHERE expires_at < NOW()`).

fayda_mcp-0.1.0/docs/configuration.md

@@ -0,0 +1,67 @@
+# Configuration Guide
+
+The `fayda-mcp` library is configured via `FaydaConfig`. It separates Relying Party (RP) credentials from runtime policies and infrastructure adapters.
+
+## Environment Variables
+
+Developers can configure their environment using a `.env` file or environment variables:
+
+| Variable | Description | Example (Sandbox) |
+|---|---|---|
+| `FAYDA_CLIENT_ID` | Registered Fayda relying party client ID | `acme_service_client_1` |
+| `FAYDA_REDIRECT_URI` | Registered callback URL on the host application | `https://my-app.example/auth/fayda/callback` |
+| `FAYDA_ISSUER_URL` | Fayda OIDC issuer base URL | `https://esignet.sandbox.fayda.et` |
+| `FAYDA_AUTHORIZATION_URL` | Fayda eSignet user authorization endpoint | `https://esignet.sandbox.fayda.et/authorize` |
+| `FAYDA_TOKEN_URL` | Fayda token exchange endpoint | `https://esignet.sandbox.fayda.et/v1/esignet/oauth/v2/token` |
+| `FAYDA_USERINFO_URL` | Fayda UserInfo claims endpoint | `https://esignet.sandbox.fayda.et/v1/esignet/oidc/userinfo` |
+| `FAYDA_JWKS_URL` | Fayda public key JWKS endpoint | `https://esignet.sandbox.fayda.et/v1/esignet/oauth/v2/jwks` |
+| `FAYDA_SIGNING_KEY_PATH` | Path to host private RSA key for `private_key_jwt` | `/run/secrets/fayda_private_key.json` |
+| `FAYDA_SESSION_TTL_SECONDS` | TTL for pending OIDC state & PKCE verifiers (default: 600s) | `600` |
+| `FAYDA_RESULT_TTL_SECONDS` | TTL for completed verification results (default: 900s) | `900` |
+
+---
+
+## Loading Configuration
+
+### 1. From Environment (`FaydaConfig.from_env()`)
+
+Loads standard environment variables with prefix `FAYDA_`:
+
+```python
+from fayda_mcp import FaydaConfig
+
+config = FaydaConfig.from_env()
+```
+
+### 2. Sandbox Preset (`FaydaConfig.sandbox()`)
+
+Quickly pre-populates official Ethiopian Fayda eSignet sandbox endpoints:
+
+```python
+from fayda_mcp import FaydaConfig
+
+config = FaydaConfig.sandbox(
+    client_id="your_sandbox_client_id",
+    redirect_uri="http://localhost:8000/auth/fayda/callback",
+    signing_key_path="secrets/fayda_private_key.pem",
+)
+```
+
+### 3. Explicit Production Configuration
+
+```python
+from fayda_mcp import FaydaConfig
+
+config = FaydaConfig(
+    client_id="prod_client_id",
+    redirect_uri="https://app.example.com/auth/fayda/callback",
+    issuer="https://esignet.ida.fayda.et",
+    authorization_endpoint="https://esignet.ida.fayda.et/authorize",
+    token_endpoint="https://esignet.ida.fayda.et/v1/esignet/oauth/v2/token",
+    userinfo_endpoint="https://esignet.ida.fayda.et/v1/esignet/oidc/userinfo",
+    jwks_uri="https://esignet.ida.fayda.et/v1/esignet/oauth/v2/jwks",
+    signing_key_path="/run/secrets/fayda_key.pem",
+    session_ttl_seconds=300,
+    result_ttl_seconds=600,
+)
+```

fayda_mcp-0.1.0/docs/credentials.md

@@ -0,0 +1,70 @@
+# Credential Ownership & Cryptography
+
+The `fayda-mcp` library adheres to a zero-secret design:
+- **No hardcoded credentials**: The library contains zero client IDs, secret keys, or test credentials.
+- **Host ownership**: The integrating host application owns and manages its Relying Party registration with National ID / Fayda (eSignet).
+- **Private key isolation**: Private keys never leave the host environment and are never transmitted over the Model Context Protocol.
+
+---
+
+## 1. Authentication Method: `private_key_jwt`
+
+Fayda eSignet uses RFC 7523 `private_key_jwt` authentication at the token endpoint instead of shared client secrets.
+
+To authenticate:
+1. The host signs an assertion JWT using its private RSA key (`RS256`).
+2. Fayda verifies the signature using the host's public JWKS registered during Relying Party onboarding.
+3. No shared secret is ever transmitted over the wire.
+
+---
+
+## 2. Generating Your Keypair
+
+Generate a standard 2048-bit or 4096-bit RSA keypair:
+
+```bash
+# Generate private key
+openssl genrsa -out fayda_private_key.pem 2048
+
+# Extract public key to register with Fayda
+openssl rsa -in fayda_private_key.pem -pubout -out fayda_public_key.pem
+```
+
+Alternatively, you can export a JSON Web Key (JWK) containing the `kty: "RSA"`, `kid`, `n`, and `e` fields for registration in the Fayda Developer Portal.
+
+---
+
+## 3. Configuring the Private Key
+
+### Option A: Local File Path
+Provide the path to your PEM or JWK private key file via configuration:
+
+```python
+from fayda_mcp import FaydaConfig
+
+config = FaydaConfig(
+    client_id="my_registered_client_id",
+    redirect_uri="https://app.example/callback",
+    signing_key_path="/run/secrets/fayda_private_key.pem",
+    ...,
+)
+```
+
+### Option B: Cloud Secret Managers (`KeyProvider` Interface)
+In production, avoid storing private keys on disk. Implement the `KeyProvider` protocol to resolve keys from AWS Secrets Manager, GCP Secret Manager, or HashiCorp Vault:
+
+```python
+from fayda_mcp.secrets.protocols import KeyProvider
+
+class VaultKeyProvider(KeyProvider):
+    async def get_private_key(self) -> str:
+        # Fetch private key PEM from HashiCorp Vault or AWS Secrets Manager
+        return await vault_client.read_secret("fayda/private_key")
+
+service = FaydaVerificationService(
+    config=config,
+    sessions=sessions,
+    results=results,
+    key_provider=VaultKeyProvider(),
+)
+```

fayda_mcp-0.1.0/examples/fastapi_server.py

@@ -0,0 +1,69 @@
+"""Example mounting Fayda FastMCP server into FastAPI with callback route."""
+
+from fastapi import FastAPI, Request
+from fastapi.responses import RedirectResponse
+from fayda_mcp import FaydaConfig, FaydaVerificationService
+from fayda_mcp.storage.memory import MemoryResultRepository, MemorySessionStore
+from fayda_mcp.mcp.factory import create_mcp_server
+from fayda_mcp.integrations.fastapi import (
+    create_callback_router,
+    create_combined_lifespan,
+)
+
+# 1. Host Fayda Configuration
+config = FaydaConfig(
+    client_id="demo-client",
+    redirect_uri="http://localhost:8000/auth/fayda/callback",
+    issuer="https://esignet.sandbox.fayda.et",
+    authorization_endpoint="https://esignet.sandbox.fayda.et/authorize",
+    token_endpoint="https://esignet.sandbox.fayda.et/oauth/token",
+    userinfo_endpoint="https://esignet.sandbox.fayda.et/oidc/userinfo",
+    jwks_uri="https://esignet.sandbox.fayda.et/jwks.json",
+)
+
+# 2. Service instance with storage contracts
+service = FaydaVerificationService(
+    config=config,
+    sessions=MemorySessionStore(),
+    results=MemoryResultRepository(),
+)
+
+# 3. FastMCP server instance
+mcp_server = create_mcp_server(service=service)
+
+# 4. Combined lifecycle ensuring both service and MCP lifespans run cleanly
+lifespan = create_combined_lifespan(
+    service=service,
+    mcp_server=mcp_server,
+)
+
+# 5. Host FastAPI application
+app = FastAPI(title="Developer Host App", lifespan=lifespan)
+
+# Mount MCP endpoint
+app.mount("/mcp", mcp_server.http_app())
+
+
+# 6. Host session-binding hook (extracts cookie or session header)
+def host_session_binding(request: Request) -> str | None:
+    return request.cookies.get("host_session_token")
+
+
+# 7. Mount callback router matching host registered redirect URI
+app.include_router(
+    create_callback_router(
+        service=service,
+        session_binding_hook=host_session_binding,
+        on_success=lambda req, result: {"status": "success", "result": result},
+    )
+)
+
+
+@app.get("/health")
+async def health():
+    return {"status": "ok"}
+
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=8000)