mcpshield 0.1.0

MCPShield - Secure access for AI agents with deterministic policy enforcement

MCPShield

Secure PostgreSQL access for AI agents with deterministic policy enforcement and comprehensive auditing.

Features

• MCP Server: Claude Code compatible stdio protocol
• PostgreSQL Tools: Safe, policy-enforced database access
• Fail-Closed Policy Engine: YAML-based security rules with default deny
• Centralized Policy Management: Policies authored in dashboard, automatically synced
• Audit Trail: Complete event logging to MCPShield control plane with policy_hash tracking
• Event Spooling: Never lose audit events, even when offline
• Developer-Friendly: Clear logs, helpful errors, easy configuration

Quick Start

Installation

pip install mcpshield

Setup

1. Create project and policy in MCPShield dashboard:

   • Go to https://app.mcpshield.xyz
   • Create project → Get Project ID
   • Create policy → Define security rules
   • Create API key

2. Create configuration file (mcpshield.yaml):

   database:
     dsn: null  # Set via PG_DSN env var
   
   api:
     base_url: "https://api.mcpshield.xyz"
     project_id: null  # Set via PROJECT_ID env var
     api_key: null  # Set via MCPSHIELD_API_KEY env var
   
   policy:
     source: "remote_with_fallback"
     file: "policy.yaml"  # Fallback only
     refresh_seconds: 60
   

3. Set environment variables:

   export PG_DSN="postgresql://user:pass@localhost:5432/dbname"
   export MCPSHIELD_API_KEY="mcps_your_key"
   export PROJECT_ID="proj_your_id"
   export API_BASE_URL="https://api.mcpshield.xyz"
   

4. Verify setup:

   mcpshield doctor --config mcpshield.yaml
   

5. Run the gateway:

   mcpshield serve --config mcpshield.yaml
   

Claude Code Integration

Add to your Claude Code MCP configuration (~/.claude/mcp.json):

{
  "mcpServers": {
    "mcpshield": {
      "command": "mcpshield",
      "args": ["serve", "--config", "/path/to/mcpshield.yaml"],
      "env": {
        "PG_DSN": "postgresql://user:pass@localhost:5432/db",
        "MCPSHIELD_API_KEY": "mcps_...",
        "PROJECT_ID": "proj_...",
        "API_BASE_URL": "https://api.mcpshield.xyz"
      }
    }
  }
}

How Policy Synchronization Works

┌──────────────────────────────────────────────────────────────┐
│                     MCPShield Dashboard                      │
│                                                              │
│  1. Author policy in UI                                      │
│  2. Save policy (stored in database)                         │
│  3. policy_hash computed (SHA-256)                           │
└──────────────────────────┬───────────────────────────────────┘
                           │
                           │ GET /projects/{id}/policy
                           │
                           ▼
                  ┌────────────────────┐
                  │  MCPShield Gateway │
                  │                    │
                  │  On startup:       │
                  │  • Fetch policy    │
                  │  • Cache locally   │
                  │  • Compute hash    │
                  │                    │
                  │  Every 60s:        │
                  │  • Re-fetch policy │
                  │  • Update cache    │
                  │  • Update hash     │
                  └────────────────────┘
                           │
                           │ Every request includes:
                           │ • decision (allow/deny)
                           │ • policy_hash
                           │
                           ▼
                  ┌────────────────────┐
                  │   Audit Events     │
                  │                    │
                  │  {                 │
                  │    decision: allow │
                  │    policy_hash:... │
                  │  }                 │
                  └────────────────────┘

Policy Source Options

remote (Recommended for production):

• Fetches policy from MCPShield API only
• Fails if API unreachable (fail-closed)
• Always uses latest policy from dashboard

remote_with_fallback (Recommended for development):

• Tries API first
• Falls back to cached policy if API fails
• Falls back to local file if cache unavailable
• Provides resilience during API outages

local:

• Uses local policy file only
• No API calls
• Useful for offline development

Fail-Closed Behavior

Gateway WILL NOT start if:

• Policy source is remote and API is unreachable
• Policy source is remote_with_fallback and ALL of: API fails, no cache, no local file
• This ensures gateway never operates without a policy

Documentation

• User Guide: https://mcpshield.xyz/docs
• Policy Syntax: https://mcpshield.xyz/docs/policy
• Troubleshooting: https://mcpshield.xyz/docs/troubleshooting

Security

MCPShield is designed with security-first principles:

• Default Deny: All operations blocked unless explicitly allowed
• Read-Only Enforcement: Blocks destructive SQL keywords
• Schema Validation: Only access allowed tables
• Data Redaction: Remove sensitive data (emails, phones) from results
• Rate Limiting: Enforce query limits and timeouts
• Audit Everything: Complete audit trail with policy_hash tracking

CLI Commands

# Run the gateway
mcpshield serve --config mcpshield.yaml

# Validate configuration
mcpshield validate --config mcpshield.yaml

# Run diagnostics
mcpshield doctor --config mcpshield.yaml

Support

• Documentation: https://mcpshield.xyz/docs
• Issues: Report via MCPShield support channels

License

MIT License - see LICENSE file for details