MCP Integration Guide

Model Context Protocol (MCP) Integration for Fulcrum AI Governance

Introduction to MCP

The Model Context Protocol (MCP) is an open standard that enables AI assistants to securely connect with external data sources and tools. Developed by Anthropic, MCP provides a standardized way for AI agents to:

Access external resources (files, databases, APIs)
Execute tools with defined schemas
Maintain context across interactions
Operate within defined security boundaries

MCP follows a client-server architecture where: - MCP Clients (Claude Desktop, Cursor, VS Code extensions) connect to servers - MCP Servers expose tools and resources to clients via JSON-RPC over stdio

Fulcrum implements an MCP server that brings enterprise governance capabilities directly into your AI development workflow, enabling real-time policy enforcement before agent actions execute.

Protocol Version: 2024-11-05

Fulcrum MCP Server Overview

The Fulcrum MCP Server acts as a governance gateway for AI agents. When integrated with your development environment, it enables AI assistants to:

Check governance policies before executing sensitive actions
View active policies that govern the current tenant
Access audit trails of recent execution envelopes

Architecture

+-------------------+     stdio      +----------------------+
|                   | <----------->  |                      |
|   Claude Desktop  |   JSON-RPC     |  Fulcrum MCP Server  |
|   Cursor          |                |                      |
|   VS Code         |                +----------+-----------+
|                   |                           |
+-------------------+                           |
                                               v
                              +----------------+----------------+
                              |                                 |
                              |    Fulcrum Control Plane        |
                              |    - Policy Engine              |
                              |    - Cost Engine                |
                              |    - Event Store                |
                              |                                 |
                              +---------------------------------+

Server Capabilities

Capability	Description
Tools	`check_governance` for policy evaluation
Resources	Live policy and envelope data access
Protocol	MCP 2024-11-05 specification compliant
Transport	stdio (standard input/output)
Multi-tenant	Scoped to specific tenant ID

Tools and Resources

Tool: `check_governance`

The primary tool exposed by the Fulcrum MCP server. Use this to evaluate whether an agent action is permitted by governance policies before execution.

Input Schema:

{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "description": "Description of the action the agent wants to perform"
    },
    "workflow": {
      "type": "string",
      "description": "The current workflow ID (optional)"
    },
    "model_id": {
      "type": "string",
      "description": "The LLM model being used (optional)"
    },
    "input_text": {
      "type": "string",
      "description": "The raw input from the user (optional)"
    }
  },
  "required": ["action"]
}

Response Decisions:

Decision	Symbol	Meaning
`ALLOW`	`[check mark]`	Proceed with action
`DENY`	`[x]`	Action blocked by policy
`WARN`	`[warning]`	Proceed with caution, policy triggered
`REQUIRE_APPROVAL`	`[pause]`	Human approval required before proceeding

Example Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "check_governance",
    "arguments": {
      "action": "Delete all records from the users table",
      "workflow": "data-cleanup-workflow",
      "model_id": "claude-3-opus",
      "input_text": "Please clean up the old user data"
    }
  }
}

Example Response (Denied):

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[x] GOVERNANCE_CHECK: DENIED. Destructive database operations require explicit approval from a system administrator."
      }
    ],
    "isError": true
  }
}

Resource: `policies://active`

Access the set of governance policies currently being enforced for your tenant.

URI: policies://active MIME Type: application/json Description: Returns all active policies with their rules, conditions, and enforcement levels.

Example Usage:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "resources/read",
  "params": {
    "uri": "policies://active"
  }
}

Resource: `envelopes://latest`

Access the audit trail of recent execution envelopes for your tenant.

URI: envelopes://latest MIME Type: application/json Description: Chronological list of the most recent execution envelopes, showing governance decisions, token usage, and outcomes.

Example Response:

Latest Envelopes Summary:
- env_8k2l: ALLOWED (Tokens: 450)
- env_1j9p: WARNED (Sensitive Pattern)
- env_9z3q: DENIED (Restricted Model)

Installation Methods

Method 1: Go Install (Recommended for Development)

# Install the Fulcrum MCP server binary
go install github.com/fulcrum-io/fulcrum/cmd/fulcrum-mcp@latest

# Verify installation
fulcrum-mcp --help

Method 2: Docker (Recommended for Production)

# Pull the official image
docker pull ghcr.io/fulcrum-governance/fulcrum-mcp:latest

# Or build from source
git clone https://github.com/Fulcrum-Governance/fulcrum-io.git
cd fulcrum-io
docker build -f cmd/fulcrum-mcp/Dockerfile -t fulcrum-mcp .

Method 3: Build from Source

# Clone the repository
git clone https://github.com/Fulcrum-Governance/fulcrum-io.git
cd fulcrum-io

# Build the MCP server
go build -o fulcrum-mcp ./cmd/fulcrum-mcp

# Move to PATH (optional)
sudo mv fulcrum-mcp /usr/local/bin/

Prerequisites

The Fulcrum MCP server requires:

Dependency	Purpose	Connection String
PostgreSQL	Policy storage	`DATABASE_URL`
Redis	Policy cache	`REDIS_URL`

Ensure your Fulcrum stack is running before starting the MCP server.

Client Configuration

Claude Desktop

Claude Desktop is the flagship MCP client from Anthropic. Configure it to use Fulcrum governance by editing the configuration file.

Configuration File Locations:

OS	Path
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`
Linux	`~/.config/Claude/claude_desktop_config.json`

Option A: Native Binary

If you have fulcrum-mcp installed locally:

{
  "mcpServers": {
    "fulcrum-governance": {
      "command": "fulcrum-mcp",
      "args": [],
      "env": {
        "DATABASE_URL": "postgresql://fulcrum:password@localhost:5432/fulcrum?sslmode=disable",
        "REDIS_URL": "redis://localhost:6379",
        "FULCRUM_TENANT_ID": "your-tenant-id"
      }
    }
  }
}

Option B: Docker Container

For isolated, reproducible deployments:

{
  "mcpServers": {
    "fulcrum-governance": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--network", "host",
        "-e", "DATABASE_URL=postgresql://fulcrum:password@localhost:5432/fulcrum?sslmode=disable",
        "-e", "REDIS_URL=redis://localhost:6379",
        "-e", "FULCRUM_TENANT_ID=your-tenant-id",
        "ghcr.io/fulcrum-governance/fulcrum-mcp:latest"
      ]
    }
  }
}

Option C: Cloud-Connected (Production)

Connect to your production Fulcrum instance:

{
  "mcpServers": {
    "fulcrum-governance": {
      "command": "fulcrum-mcp",
      "args": [],
      "env": {
        "FULCRUM_API_ENDPOINT": "api.fulcrum.dev:443",
        "FULCRUM_API_KEY": "your-api-key",
        "FULCRUM_TENANT_ID": "your-tenant-id"
      }
    }
  }
}

After saving the configuration, restart Claude Desktop to load the MCP server.

Cursor

Cursor supports MCP servers through its settings interface. Configure Fulcrum by adding the server definition.

Configuration File: ~/.cursor/mcp.json (or via Settings > MCP Servers)

{
  "mcpServers": {
    "fulcrum-governance": {
      "command": "fulcrum-mcp",
      "args": [],
      "env": {
        "DATABASE_URL": "postgresql://fulcrum:password@localhost:5432/fulcrum?sslmode=disable",
        "REDIS_URL": "redis://localhost:6379",
        "FULCRUM_TENANT_ID": "your-tenant-id"
      }
    }
  }
}

Alternative via UI:

Open Cursor Settings (Cmd/Ctrl + ,)
Navigate to Features > MCP Servers
Click Add Server
Enter:
Name: fulcrum-governance
Command: fulcrum-mcp
Environment Variables: (as above)
Save and restart Cursor

VS Code

VS Code requires an MCP extension to support MCP servers. Several community extensions are available.

Using Claude Dev Extension

If using the Claude Dev extension:

Configuration File: .vscode/mcp-servers.json (workspace) or global settings

{
  "mcpServers": {
    "fulcrum-governance": {
      "command": "fulcrum-mcp",
      "env": {
        "DATABASE_URL": "postgresql://fulcrum:password@localhost:5432/fulcrum?sslmode=disable",
        "REDIS_URL": "redis://localhost:6379",
        "FULCRUM_TENANT_ID": "your-tenant-id"
      }
    }
  }
}

Using Continue Extension

For the Continue extension, add to ~/.continue/config.json:

{
  "experimental": {
    "mcpServers": {
      "fulcrum-governance": {
        "transport": {
          "type": "stdio",
          "command": "fulcrum-mcp",
          "env": {
            "DATABASE_URL": "postgresql://fulcrum:password@localhost:5432/fulcrum?sslmode=disable",
            "REDIS_URL": "redis://localhost:6379",
            "FULCRUM_TENANT_ID": "your-tenant-id"
          }
        }
      }
    }
  }
}

Other MCP Clients

Windsurf (Codeium)

Windsurf supports MCP through its configuration system:

{
  "mcpServers": {
    "fulcrum-governance": {
      "command": "fulcrum-mcp",
      "args": [],
      "env": {
        "DATABASE_URL": "postgresql://fulcrum:password@localhost:5432/fulcrum?sslmode=disable",
        "REDIS_URL": "redis://localhost:6379",
        "FULCRUM_TENANT_ID": "your-tenant-id"
      }
    }
  }
}

Generic MCP Client

For any MCP-compatible client, the server configuration follows this pattern:

{
  "name": "fulcrum-governance",
  "transport": {
    "type": "stdio",
    "command": "fulcrum-mcp",
    "args": [],
    "env": {
      "DATABASE_URL": "<postgres-connection-string>",
      "REDIS_URL": "<redis-connection-string>",
      "FULCRUM_TENANT_ID": "<your-tenant-id>"
    }
  }
}

Testing Your Integration

Step 1: Verify Server Startup

Test that the MCP server starts correctly:

# Set environment variables
export DATABASE_URL="postgresql://fulcrum:password@localhost:5432/fulcrum?sslmode=disable"
export REDIS_URL="redis://localhost:6379"
export FULCRUM_TENANT_ID="test-tenant"

# Start the server manually
fulcrum-mcp

# You should see:
# Fulcrum MCP Governance Server starting for tenant: test-tenant

Step 2: Test Tool Listing

Send a tools/list request to verify the server exposes the check_governance tool:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | fulcrum-mcp

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "check_governance",
        "description": "Evaluate an agent action against Fulcrum governance policies.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "action": {"type": "string", "description": "The description of the action the agent wants to perform"},
            "workflow": {"type": "string", "description": "The current workflow ID"},
            "model_id": {"type": "string", "description": "The LLM model being used"},
            "input_text": {"type": "string", "description": "The raw input from the user"}
          },
          "required": ["action"]
        }
      }
    ]
  }
}

Step 3: Test Resource Listing

echo '{"jsonrpc":"2.0","id":2,"method":"resources/list","params":{}}' | fulcrum-mcp

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "resources": [
      {
        "uri": "envelopes://latest",
        "name": "Latest Envelopes",
        "description": "Chronological list of the most recent execution envelopes for this tenant.",
        "mimeType": "application/json"
      },
      {
        "uri": "policies://active",
        "name": "Active Policies",
        "description": "The set of governance policies currently being enforced.",
        "mimeType": "application/json"
      }
    ]
  }
}

Step 4: Test Governance Check

echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"check_governance","arguments":{"action":"Send email to all users"}}}' | fulcrum-mcp

Step 5: Verify in Claude Desktop

Open Claude Desktop
Look for the MCP server indicator (hammer icon)
Click to see available tools
Verify "fulcrum-governance" appears with check_governance tool
Ask Claude: "What governance tools do you have access to?"

Troubleshooting

Common Issues

1. Server Not Appearing in Client

Symptoms: MCP server not listed in Claude Desktop/Cursor

Solutions: - Verify the configuration file path is correct - Ensure JSON syntax is valid (use a JSON validator) - Restart the client application completely - Check that the fulcrum-mcp binary is in your PATH

# Verify binary is accessible
which fulcrum-mcp

# Test it can be executed
fulcrum-mcp --help

2. Database Connection Failed

Symptoms: Server starts but tool calls fail with database errors

Solutions: - Verify PostgreSQL is running and accessible - Check the DATABASE_URL format - Ensure the database and schema exist

# Test database connection
psql "postgresql://fulcrum:password@localhost:5432/fulcrum"

# Verify Fulcrum schema exists
\dt fulcrum.*

3. Redis Connection Failed

Symptoms: Server fails to start with Redis errors

Solutions: - Verify Redis is running - Check the REDIS_URL format

# Test Redis connection
redis-cli -u redis://localhost:6379 PING
# Should return: PONG

4. Tenant Not Found

Symptoms: check_governance returns "no policies found"

Solutions: - Verify FULCRUM_TENANT_ID is correct - Ensure the tenant exists in the database - Check that policies are active for the tenant

-- Check tenant exists
SELECT * FROM fulcrum.tenants WHERE id = 'your-tenant-id';

-- Check active policies
SELECT * FROM fulcrum.policies
WHERE tenant_id = 'your-tenant-id'
AND status = 'ACTIVE';

5. Docker Networking Issues

Symptoms: Container cannot reach host services

Solutions:

For macOS/Windows:

{
  "args": [
    "run", "-i", "--rm",
    "-e", "DATABASE_URL=postgresql://fulcrum:password@host.docker.internal:5432/fulcrum",
    "-e", "REDIS_URL=redis://host.docker.internal:6379",
    "fulcrum-mcp"
  ]
}

For Linux:

{
  "args": [
    "run", "-i", "--rm",
    "--network", "host",
    "-e", "DATABASE_URL=postgresql://fulcrum:password@localhost:5432/fulcrum",
    "-e", "REDIS_URL=redis://localhost:6379",
    "fulcrum-mcp"
  ]
}

6. Permission Denied on Binary

Symptoms: "Permission denied" when starting server