FINOS AI Governance MCP Server

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.

Related MCP server: MCP Enhanced Data Retrieval System

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)

Risk & Mitigation Tools (4)

System Monitoring Tools (2)

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

Mitigation Categories

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.

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