MCP Setup

Connect 9 MCP servers to your AI client.

Connect via MCP Proxy (recommended — remote, API key auth, per-tool permissions) or direct stdio for local development. All 254 tools, all 9 GRC domains, any MCP-compatible client.

Before you start

Prerequisites

Docker stack running

docker compose up -d from the repo root

Node.js 20+

Required for npx and tsx to run MCP servers

Database seeded

Demo data is auto-seeded on first docker compose up

Claude Code or Desktop

Any MCP-compatible client works

Option 1

Claude Code

Run these commands from the riskready-community directory. Each command registers one MCP server with its database connection.

Terminal — add all 9 servers
# From the riskready-community directory:

$ claude mcp add riskready-controls -e DATABASE_URL=postgresql://riskready:change-me@localhost:5434/riskready -- npx tsx apps/mcp-server-controls/src/index.ts
$ claude mcp add riskready-risks -e DATABASE_URL=postgresql://riskready:change-me@localhost:5434/riskready -- npx tsx apps/mcp-server-risks/src/index.ts
$ claude mcp add riskready-policies -e DATABASE_URL=postgresql://riskready:change-me@localhost:5434/riskready -- npx tsx apps/mcp-server-policies/src/index.ts
$ claude mcp add riskready-organisation -e DATABASE_URL=postgresql://riskready:change-me@localhost:5434/riskready -- npx tsx apps/mcp-server-organisation/src/index.ts
$ claude mcp add riskready-itsm -e DATABASE_URL=postgresql://riskready:change-me@localhost:5434/riskready -- npx tsx apps/mcp-server-itsm/src/index.ts
$ claude mcp add riskready-incidents -e DATABASE_URL=postgresql://riskready:change-me@localhost:5434/riskready -- npx tsx apps/mcp-server-incidents/src/index.ts
$ claude mcp add riskready-evidence -e DATABASE_URL=postgresql://riskready:change-me@localhost:5434/riskready -- npx tsx apps/mcp-server-evidence/src/index.ts
$ claude mcp add riskready-audits -e DATABASE_URL=postgresql://riskready:change-me@localhost:5434/riskready -- npx tsx apps/mcp-server-audits/src/index.ts
$ claude mcp add riskready-agent-ops -e DATABASE_URL=postgresql://riskready:change-me@localhost:5434/riskready -- npx tsx apps/mcp-server-agent-ops/src/index.ts

Note: Update the DATABASE_URL if you changed the default password or port in your .env file. The default port is 5434 and password is change-me.

Option 2

Claude Desktop

Add the servers to your claude_desktop_config.json. Update the cwd path to point to your local clone of the repository.

claude_desktop_config.json
{
  "mcpServers": {
    "riskready-controls": {
      "command": "npx",
      "args": [
        "tsx",
        "apps/mcp-server-controls/src/index.ts"
      ],
      "cwd": "/path/to/riskready-community",
      "env": {
        "DATABASE_URL": "postgresql://riskready:change-me@localhost:5434/riskready"
      }
    },
    "riskready-risks": {
      "command": "npx",
      "args": [
        "tsx",
        "apps/mcp-server-risks/src/index.ts"
      ],
      "cwd": "/path/to/riskready-community",
      "env": {
        "DATABASE_URL": "postgresql://riskready:change-me@localhost:5434/riskready"
      }
    },
    "riskready-policies": {
      "command": "npx",
      "args": [
        "tsx",
        "apps/mcp-server-policies/src/index.ts"
      ],
      "cwd": "/path/to/riskready-community",
      "env": {
        "DATABASE_URL": "postgresql://riskready:change-me@localhost:5434/riskready"
      }
    },
    "riskready-organisation": {
      "command": "npx",
      "args": [
        "tsx",
        "apps/mcp-server-organisation/src/index.ts"
      ],
      "cwd": "/path/to/riskready-community",
      "env": {
        "DATABASE_URL": "postgresql://riskready:change-me@localhost:5434/riskready"
      }
    },
    "riskready-itsm": {
      "command": "npx",
      "args": [
        "tsx",
        "apps/mcp-server-itsm/src/index.ts"
      ],
      "cwd": "/path/to/riskready-community",
      "env": {
        "DATABASE_URL": "postgresql://riskready:change-me@localhost:5434/riskready"
      }
    },
    "riskready-incidents": {
      "command": "npx",
      "args": [
        "tsx",
        "apps/mcp-server-incidents/src/index.ts"
      ],
      "cwd": "/path/to/riskready-community",
      "env": {
        "DATABASE_URL": "postgresql://riskready:change-me@localhost:5434/riskready"
      }
    },
    "riskready-evidence": {
      "command": "npx",
      "args": [
        "tsx",
        "apps/mcp-server-evidence/src/index.ts"
      ],
      "cwd": "/path/to/riskready-community",
      "env": {
        "DATABASE_URL": "postgresql://riskready:change-me@localhost:5434/riskready"
      }
    },
    "riskready-audits": {
      "command": "npx",
      "args": [
        "tsx",
        "apps/mcp-server-audits/src/index.ts"
      ],
      "cwd": "/path/to/riskready-community",
      "env": {
        "DATABASE_URL": "postgresql://riskready:change-me@localhost:5434/riskready"
      }
    },
    "riskready-agent-ops": {
      "command": "npx",
      "args": [
        "tsx",
        "apps/mcp-server-agent-ops/src/index.ts"
      ],
      "cwd": "/path/to/riskready-community",
      "env": {
        "DATABASE_URL": "postgresql://riskready:change-me@localhost:5434/riskready"
      }
    }
  }
}

Important: Replace /path/to/riskready-community with the actual path to your cloned repository. The cwd field ensures each server resolves the Prisma client correctly.

Option 3 — Recommended

MCP Proxy (Remote)

Connect Claude Desktop to your RiskReady instance over the network — one endpoint, one API key, all 254 tools. No local Node.js required. Full security controls: per-user authentication, org scoping, audit logging, per-tool permission scoping, and rate limiting.

Step 1 — Create an API Key

1

Log into your RiskReady instance

2

Navigate to Settings → AI Configuration

3

Scroll to MCP API Keys

4

Click Create Key — give it a name (e.g. "My Laptop")

5

Copy the key (starts with rr_sk_) — it's shown only once

Step 2 — Configure Claude Desktop

claude_desktop_config.json
{
  "mcpServers": {
    "riskready": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://your-riskready-server/mcp",
        "--header",
        "Authorization: Bearer rr_sk_your_api_key_here"
      ]
    }
  }
}

Replace: your-riskready-server with your instance URL (e.g. 192.168.1.100:9380 for LAN or a Tailscale/VPN address) and rr_sk_your_api_key_here with the key from Step 1.

Security Controls — Built In

Per-user API key

rr_sk_ prefix, bcrypt hashed, instantly revocable

Per-tool permissions

Scope keys to read-only, write, or specific domains

Org isolation

organisationId injected on every tool call

Audit logging

Every tool call logged: user, tool, org, duration

Rate limiting

100 tool calls/minute per key

Credential scanning

API keys and PII stripped from tool results

Reference

All 9 servers at a glance

Server
Tools
Capabilities
riskready-controls
66
Controls, SoA, assessments, metrics
riskready-risks
34
Risk register, scenarios, KRIs, treatments
riskready-policies
23
Policies, reviews, exceptions, mappings
riskready-organisation
35
Org profile, departments, committees
riskready-itsm
40
CMDB assets, changes, capacity
riskready-incidents
19
Incidents, timelines, lessons learned
riskready-evidence
16
Evidence records, requests, coverage
riskready-audits
14
Nonconformities, CAP workflows
riskready-agent-ops
7
Action status, task tracking
Total: 254 tools across 9 servers

Try these

Example queries once connected

Query

“Show me all controls that are not yet implemented”

Query

“What is our current risk heat map?”

Analysis

“Run a gap analysis on our latest assessment”

Analysis

“Which KRIs are in RED status?”

Mutation

“Create a new risk for insider data exfiltration”

Mutation

“Raise a nonconformity for the failed access control test”

Council

“Prepare a board report on our overall GRC maturity”

Self-check

“What is the status of my last proposal?”

Mutations are safe. Every write action (create, update, delete) is proposed into the approval queue at /settings/mcp-approvals — nothing changes in the database until a human approves it.

Common issues

Troubleshooting

MCP server fails to start
Check that Node.js 20+ is installed, npx/tsx are on your PATH, and DATABASE_URL points to a running PostgreSQL instance. Run docker compose ps to verify the database container is healthy.
Tools return no data
Verify the database is seeded — demo data loads automatically on first docker compose up. Try a broad query like "list all controls" to confirm connectivity.
Connection refused on port 5434
The database container may not be running. Run docker compose up -d db and wait for the health check to pass. If you changed DB_PORT in .env, update your DATABASE_URL accordingly.
Proposed actions not appearing
Check /settings/mcp-approvals in the web UI. Verify the DATABASE_URL user has INSERT permissions on the McpPendingAction table.

Full reference in the repo.

This page covers quick setup. For tool-by-tool documentation, council configuration, scheduled workflows, and advanced troubleshooting, see the canonical docs in GitHub.

AI Assistant GuideMCP Server Reference