FINOS AI Governance MCP Server

<!-- Core Project Badges -->

<!-- Quality & CI Badges -->

<!-- Tools & Features -->

AI governance framework document access through the Model Context Protocol.

This project provides direct access to AI governance framework documents from FINOS repositories through MCP, making them available in Claude, VS Code, Cursor, and other supported tools.

---

Quick Start

# Clone the repository
git clone https://github.com/finos/aigf-mcp-server.git
cd aigf-mcp-server

# Create and activate a virtual environment
python -m venv venv

# On Windows:
venv\Scripts\activate

# On macOS/Linux:
source venv/bin/activate

# Install dependencies
pip install -e .

# Required security setting (generate your own value; choose one)
export FINOS_MCP_CACHE_SECRET=$(python -c "import secrets; print(secrets.token_hex(32))")
# OR
export FINOS_MCP_CACHE_SECRET=$(openssl rand -hex 32)

# Test
finos-mcp --help
mcp list tools

Note: Using a virtual environment isolates project dependencies from your system Python, preventing conflicts and keeping your environment clean. This is the recommended approach for Python development.

→ Full Setup Guide - Connect to Claude, VS Code, Cursor, etc.

---

Docker Deployment (Local + Cloud)

This repository now includes:

• Dockerfile for a production-style container image
• docker-compose.yml for local deployment

Run locally with Docker Compose

# 1) Create Docker env file
cp .env.docker.example .env.docker

# 2) Put a real 32+ char value in .env.docker
# FINOS_MCP_CACHE_SECRET=...

# 3) Start
docker compose up --build -d

# 4) Follow logs
docker compose logs -f finos-mcp-server

Server endpoint:

• http://localhost:8000/mcp

Build and run image directly

docker build -t finos-mcp-server:latest .

docker run --rm -p 8000:8000 \
  -e FINOS_MCP_CACHE_SECRET="$(openssl rand -hex 32)" \
  -e FINOS_MCP_MCP_TRANSPORT=http \
  -e FINOS_MCP_MCP_HOST=0.0.0.0 \
  -e FINOS_MCP_MCP_PORT=8000 \
  finos-mcp-server:latest

Use in AWS/GCP/Azure/Kubernetes

Use the same container image and pass environment variables at deploy time:

• FINOS_MCP_CACHE_SECRET (required, minimum 32 chars)
• FINOS_MCP_MCP_TRANSPORT=http
• FINOS_MCP_MCP_HOST=0.0.0.0
• FINOS_MCP_MCP_PORT (for example 8000)
• FINOS_MCP_GITHUB_TOKEN (recommended)
• If FINOS_MCP_MCP_AUTH_ENABLED=true, then FINOS_MCP_MCP_AUTH_ISSUER, FINOS_MCP_MCP_AUTH_AUDIENCE, and one of FINOS_MCP_MCP_AUTH_JWKS_URI or FINOS_MCP_MCP_AUTH_PUBLIC_KEY are also required.

Cloud mapping examples:

• AWS ECS/Fargate: task definition env vars + secret manager for FINOS_MCP_CACHE_SECRET
• GCP Cloud Run: container env vars + Secret Manager mount/reference
• Kubernetes: Deployment env vars + Secret for sensitive values

---

Available MCP Tools

Framework Access Tools (5)

Tool Name	Description	Use Case
list_frameworks	List all available AI governance frameworks	Get overview of the runtime-discovered framework catalog
get_framework	Get complete content of a specific framework	Retrieve complete framework document content
search_frameworks	Search for text within framework documents	Find specific content within framework documents
list_risks	List all available risk documents	Get overview of AI governance risks
get_risk	Get complete content of specific risk documents	Retrieve detailed risk documentation

Risk & Mitigation Tools (4)

Tool Name	Description	Use Case
search_risks	Search within risk documentation	Find specific risks by keyword
list_mitigations	List all available mitigation documents	Get overview of available mitigations
get_mitigation	Get complete content of specific mitigation documents	Retrieve detailed mitigation strategies
search_mitigations	Search within mitigation documentation	Find specific mitigations by keyword

System Monitoring Tools (2)

Tool Name	Description	Use Case
get_service_health	Get basic service health status	Monitor system availability and status
get_cache_stats	Get cache performance statistics	Monitor cache performance and efficiency

---

Supported Content

AI Governance Frameworks

• Framework definitions are discovered from the configured upstream repository at runtime.
• Use list_frameworks to see the current catalog available to your deployment.

---

Risk and Mitigation Categories

Risk Categories

Risk Type	Description	Example Risks
Security	Information security and cybersecurity risks	Data leakage, prompt injection, adversarial attacks
Operational	Business and operational risks	AI bias, model drift, hallucination
Privacy	Data privacy and protection risks	Data exposure, unauthorized access
Transparency	Explainability and accountability risks	Model opacity, decision traceability

Mitigation Categories

Mitigation Type	Description	Example Controls
Prevention	Proactive controls to prevent risks	Access controls, bias testing, data validation
Detection	Controls to detect and monitor risks	Performance monitoring, anomaly detection
Response	Controls to respond to identified risks	Incident response, model rollback procedures

---

Common Use Cases

Framework Research

• List Available Frameworks: Use list_frameworks to see all supported governance frameworks
• Get Framework Content: Use get_framework to retrieve complete framework documents
• Search Framework Content: Use search_frameworks to find specific text within frameworks

Risk Management

• Browse Available Risks: Use list_risks to see all documented AI governance risks
• Get Risk Details: Use get_risk to retrieve complete risk documentation
• Search Risks: Use search_risks to find specific risks by keyword

Mitigation Planning

• Browse Available Mitigations: Use list_mitigations to see all documented mitigation strategies
• Get Mitigation Details: Use get_mitigation to retrieve complete mitigation documentation
• Search Mitigations: Use search_mitigations to find specific mitigations by keyword

System Monitoring

• Health Status: Use get_service_health to monitor system availability
• Performance Metrics: Use get_cache_stats to monitor cache performance

---

Architecture

Components

• FastMCP Runtime Bootstrap (src/finos_mcp/fastmcp_server.py): FastMCP server construction, model definitions, and tool registration wiring
• API Registration Modules (src/finos_mcp/api/): Dedicated tool/resource/prompt registration and MCP payload mapping
• MCP Tools: 11 tools organized in 3 categories (Framework Access, Risk & Mitigation, System Monitoring)
• MCP Prompts: 3 prompt templates for framework analysis and risk assessment
• MCP Resources: 3 resource types with finos:// URI scheme for structured access
• Application Services and Use-Cases (src/finos_mcp/application/): Search text parsing, prompt composition, observability projection, and domain flows
• Content Management (src/finos_mcp/content/): Dynamic content loading and caching
• Security Layer (src/finos_mcp/security/): Request validation and protection
• Runtime Guardrails (src/finos_mcp/fastmcp_server.py): Middleware-based rate limiting, safe error responses, and payload size enforcement

Design Principles

• Document Access Only: Direct access to governance framework documents
• Framework Agnostic: Works with any governance framework document structure
• Modular Tool System: Easy addition and removal of tools
• Security First: All requests validated and protected
• Performance Optimized: Intelligent caching and async operations

Runtime Security Controls

• Middleware Order: Error handling -> timing -> logging -> rate limiting
• Input Limits: Tool, prompt, and resource parameters enforce max lengths and request-size checks
• Output Limits: Resource/document payloads are size-validated before returning to clients
• Error Disclosure Control: External errors are sanitized and correlation-tagged
• Failure Signaling Strategy: Dynamic GitHub discovery with explicit unavailable responses when upstream content cannot be reached
• Boundary Authentication (Optional): JWT validation at MCP boundary with issuer/audience/scope enforcement

---

Development

Setup

# Install development dependencies
pip install -e ".[dev,security,test]"

# Run CI-equivalent checks locally
./scripts/ci-local.sh

# Run tests
pytest

Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=src --cov-report=html

# Run fast tests
pytest -c pytest.fast.ini

# Test MCP server
mcp list tools

Adding New Tools

Tool additions follow the layered runtime pattern:

1. Add payload builder or registration wiring in src/finos_mcp/api/tools/
2. Add or extend use-case logic in src/finos_mcp/application/use_cases/
3. Register the MCP surface from src/finos_mcp/fastmcp_server.py
4. Add or update tests in tests/unit/ and integration coverage where needed
5. Update tool documentation

---

Configuration

Environment variables and configuration:

• Content loaded from GitHub repositories dynamically
• Cache configuration in src/finos_mcp/content/cache.py
• Security settings in src/finos_mcp/security/

Required Security Configuration

FINOS_MCP_CACHE_SECRET is required at startup.

# Option 1 (Python)
export FINOS_MCP_CACHE_SECRET=$(python -c "import secrets; print(secrets.token_hex(32))")
# Option 2 (OpenSSL)
export FINOS_MCP_CACHE_SECRET=$(openssl rand -hex 32)

Notes:

• Use a unique secret per environment.
• Do not commit real secrets to git.

MCP Auth Configuration

Use JWT validation (FastMCP JWTVerifier) to protect the MCP boundary in production.

export FINOS_MCP_MCP_AUTH_ENABLED=true
export FINOS_MCP_MCP_AUTH_ISSUER=https://auth.example.com
export FINOS_MCP_MCP_AUTH_AUDIENCE=finos-mcp-server
export FINOS_MCP_MCP_AUTH_JWKS_URI=https://auth.example.com/.well-known/jwks.json
export FINOS_MCP_MCP_AUTH_REQUIRED_SCOPES=governance:read,governance:write

Notes:

• Set exactly one of FINOS_MCP_MCP_AUTH_JWKS_URI or FINOS_MCP_MCP_AUTH_PUBLIC_KEY.
• When auth is enabled, missing issuer/audience/verifier settings fail startup.
• Clients must send Authorization: Bearer <JWT>.

MCP Transport Configuration

Transport and network binding are config-driven (no hardcoded host/port in runtime code):

# Local MCP client default
export FINOS_MCP_MCP_TRANSPORT=stdio

# HTTP exposure example
export FINOS_MCP_MCP_TRANSPORT=http
export FINOS_MCP_MCP_HOST=127.0.0.1
export FINOS_MCP_MCP_PORT=8000

Live Transport Tests

# End-to-end stdio MCP test
FINOS_RUN_LIVE_MCP_TEST=1 ./venv/bin/pytest -q tests/integration/test_live_mcp_server.py

# End-to-end HTTP MCP test (starts server + probes /mcp)
./scripts/test-http-transport.sh

# End-to-end HTTP auth boundary test (unauthorized/forbidden/authorized)
./scripts/test-auth-http-transport.sh

Advanced Configuration Reference

Use .env.example as the canonical source and override by environment in production.

Variable	Default	Required	Purpose / Guidance
FINOS_MCP_MCP_TRANSPORT	stdio	No	Runtime transport. Use stdio for local clients; use http or streamable-http for network exposure.
FINOS_MCP_MCP_HOST	127.0.0.1	For non-stdio	Bind host for network transports. Keep loopback unless behind controlled ingress.
FINOS_MCP_MCP_PORT	8000	For non-stdio	Bind port for network transports.
FINOS_MCP_MCP_AUTH_ENABLED	false	No	Enables JWT boundary authentication. Set true for production.
FINOS_MCP_MCP_AUTH_ISSUER	(none)	If auth enabled	Expected JWT iss claim.
FINOS_MCP_MCP_AUTH_AUDIENCE	(none)	If auth enabled	Expected JWT aud claim.
FINOS_MCP_MCP_AUTH_JWKS_URI	(none)	One of verifier pair	Recommended verifier source (supports key rotation).
FINOS_MCP_MCP_AUTH_PUBLIC_KEY	(none)	One of verifier pair	Static PEM verifier source. Do not set with JWKS_URI.
FINOS_MCP_MCP_AUTH_REQUIRED_SCOPES	(none)	No	Comma-separated required scopes for all requests.
FINOS_MCP_HTTP_TIMEOUT	30	No	Outbound request timeout in seconds.
FINOS_MCP_ENABLE_CACHE	true	No	In-memory content cache toggle.
FINOS_MCP_CACHE_MAX_SIZE	1000	No	Max entries in cache. Increase carefully with memory limits.
FINOS_MCP_CACHE_TTL_SECONDS	3600	No	Cache TTL in seconds.
FINOS_MCP_GITHUB_TOKEN	(none)	Recommended	Raises GitHub API limits and stability for dynamic content sync.
FINOS_MCP_LOG_LEVEL	INFO	No	Runtime log verbosity.
FINOS_MCP_DEBUG_MODE	false	No	Enables verbose diagnostics; avoid in production unless troubleshooting.

Production baseline:

• FINOS_MCP_MCP_AUTH_ENABLED=true
• FINOS_MCP_MCP_TRANSPORT=http (or streamable-http) behind TLS ingress
• FINOS_MCP_MCP_HOST=127.0.0.1 when fronted by reverse proxy
• Configure FINOS_MCP_MCP_AUTH_JWKS_URI, FINOS_MCP_MCP_AUTH_ISSUER, FINOS_MCP_MCP_AUTH_AUDIENCE

Go-Live Approval Gate

Run full automated release gates:

./scripts/go-live-gate.sh

Includes:

• tracked-folder hygiene checks
• clean working tree enforcement
• linting and type checks
• regression tests
• live stdio/HTTP/auth transport checks
• dependency vulnerability scan

---

Content Sources

Content Coverage

• Framework Data: Direct access to governance framework documents
• Dynamic Loading: Automatic content fetching from official sources
• FINOS Content: AI governance risks and mitigations from FINOS AI Governance Framework, used under CC BY 4.0 license

Performance Characteristics

• Response Times: Fast cached response times with intelligent caching
• Reliability: Circuit breaker protection and error boundary management
• Scalability: Memory-efficient design with configurable cache limits
• Security: Comprehensive DoS protection and request validation

---

Documentation

Getting Started

• Setup Guide - Connect to your editor (5 minutes)
• User Guide - Comprehensive usage guide for all tools

API & Integration

• API Documentation - Complete API reference for all 11 MCP tools
• Framework Architecture - System design and patterns
• MCP Conformance Matrix - Implemented/partial/out-of-scope capability map

Support & Troubleshooting

• Troubleshooting - Common issues and solutions
• Tools Reference - Complete guide to all 11 MCP tools
• Architecture Decision Records - Key architecture rationale and policy decisions
• GitHub Repository - Source code and issues

---

Contributing

1. Fork the repository
2. Create a feature branch
3. Make changes and add tests
4. Run CI-equivalent checks: ./scripts/ci-local.sh
5. Test with MCP CLI: mcp list tools
6. Submit a pull request

---

Need Help

• Report Issues
• Ask Questions
• Full Documentation

---

License

• Software: Apache 2.0 License
• FINOS Content: CC BY 4.0 License

---