fairmind-mcp

An MCP server that lets a coding agent ask FairMind whether an AI system may ship, and run fairness tests on CSVs from your machine. It is a thin layer over the fairmind Python SDK and talks to the server over stdio.

Tools

Each tool returns a compact text summary and the full API response as structured content. run_evaluation waits for behaviour tests, which run as background jobs and can take minutes. The evaluation tools act in the key's first organisation; set FAIRMIND_ORG_ID to pick another. API failures come back as tool errors carrying the HTTP status and the server's message. attest_check writes manual evidence, so the tool tells the agent to use only statements the user gave or confirmed.

Install

# from a checkout, with uv (the SDK is resolved from ../sdk)
cd apps/mcp && uv sync

# or with pip: SDK first, then this package
pip install -e apps/sdk -e apps/mcp

The server targets the mcp 1.x FastMCP API (mcp>=1.10,<2); in mcp 2.x it was renamed MCPServer.

Configure

Create a key once with POST /api/v1/auth/api-keys, export it, and let the client pass it through. The config below never contains the key itself.

export FAIRMIND_API_URL=https://fairmind.example.com
export FAIRMIND_API_KEY=...

Claude Code

claude mcp add fairmind -- uv run --project /path/to/fairmind/apps/mcp fairmind-mcp

The server inherits FAIRMIND_API_URL and FAIRMIND_API_KEY from the shell that starts Claude Code. To scope it to a repository, commit a .mcp.json that expands the variables from each developer's environment:

{
  "mcpServers": {
    "fairmind": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/fairmind/apps/mcp", "fairmind-mcp"],
      "env": {
        "FAIRMIND_API_URL": "${FAIRMIND_API_URL}",
        "FAIRMIND_API_KEY": "${FAIRMIND_API_KEY}"
      }
    }
  }
}

Claude Desktop

Desktop does not expand variables, so launch through a shell that reads them from your environment. In claude_desktop_config.json:

{
  "mcpServers": {
    "fairmind": {
      "command": "/bin/sh",
      "args": ["-c", "exec uv run --project /path/to/fairmind/apps/mcp fairmind-mcp"]
    }
  }
}

Set FAIRMIND_API_URL and FAIRMIND_API_KEY in the environment that starts Claude Desktop (for example with launchctl setenv on macOS), or keep them in a file outside the repository that you source in the -c command.

Try it

Ask the agent: "May the credit-scoring system ship?" It calls list_systems, then release_gate. Ask it to "run a fairness test on holdout.csv for gender and region, outcome repaid, prediction approved" and it calls run_fairness_test with the file path on your machine.

Tests

cd apps/mcp && uv run --with pytest pytest -q -p no:cacheprovider tests