@critique-mcp/mcp-gateway-wrapper

@critique-mcp/mcp-gateway-wrapper

Local stdio wrapper for Critique MCP Gateway that validates API keys on initialize calls and proxies MCP protocol to remote HTTP/SSE gateways with API key injection.

Overview

This wrapper runs locally on your machine and acts as a bridge between MCP clients (like Cursor, Claude Desktop) and remote Critique MCP Gateways. It provides:

• API Key Validation: Validates your API key on initialize calls before establishing a session
• API Key Injection: Automatically injects your API key into all MCP messages for gateway validation
• Protocol Translation: Converts stdio MCP protocol (what clients expect) to HTTP/SSE (what remote gateways use)

Installation

Using npx (Recommended)

No installation needed! Use npx to run the wrapper directly:

npx -y @critique-mcp/mcp-gateway-wrapper <gateway-url>

Global Installation

npm install -g @critique-mcp/mcp-gateway-wrapper

Then use it directly:

mcp-gateway-wrapper <gateway-url>

Configuration

MCP Client Configuration

Configure the wrapper in your MCP client settings (e.g., ~/.cursor/mcp.json or ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "critique-gateway": {
      "command": "npx",
      "args": [
        "-y",
        "@critique-mcp/mcp-gateway-wrapper",
        "http://gateways.critique.io/gateway/{client-id}/mcp"
      ],
      "env": {
        "CLIENT_API_KEY": "client-api-key-{client-id}",
        "CRITIQUE_API_URL": "http://localhost:8000"
      }
    }
  }
}

Environment Variables

• CLIENT_API_KEY (required): Your API key for authentication. This is provided by Critique when you register your client.

• CRITIQUE_API_URL (optional): The URL of the critique-api service. Defaults to http://localhost:8000.

  • For local development: http://localhost:8000
  • For production: Use your production critique-api URL

Command Line Arguments

• <gateway-url> (required): The URL of your remote MCP Gateway endpoint.

  Example: http://gateways.critique.io/gateway/d2b7c8db-de3c-43eb-a10a-aafed3d54b64/mcp

How It Works

Architecture

MCP Client (stdio)
    ↓
Local Wrapper (@critique-mcp/mcp-gateway-wrapper)
    ↓
    ├─→ Validate API Key (critique-api)
    └─→ Forward with API Key (Remote Gateway)

Initialize Validation

When the MCP client sends an initialize call:

• Wrapper intercepts the initialize call
• Validates API key by calling POST {CRITIQUE_API_URL}/api/v1/validation/initialize with X-API-Key header
• If validation fails: Returns MCP error to client, does not forward to gateway
• If validation succeeds: Forwards initialize to gateway with API key injected

API Key Injection

For all MCP messages (including initialize and tools/call):

• API key is automatically added to the X-API-Key header when forwarding to the gateway
• Gateway interceptor extracts the API key for validation on tool calls

Defense in Depth

The wrapper provides two layers of security:

• First Gate: Wrapper validates initialize call (blocks unauthorized sessions)
• Second Gate: Gateway interceptor validates every tools/call message (blocks unauthorized tool calls)

Even if a user modifies the wrapper to bypass initialize validation, the gateway interceptor still validates every tool call.

Error Handling

Missing API Key

If CLIENT_API_KEY is not set:

Error: CLIENT_API_KEY environment variable is required

Solution: Set the CLIENT_API_KEY environment variable in your MCP client configuration.

Missing Gateway URL

If gateway URL is not provided:

Error: Gateway URL is required
Usage: mcp-gateway-wrapper <gateway-url>

Solution: Provide the gateway URL as a command line argument.

Validation Failures

If API key validation fails, the wrapper returns an MCP error:

{
  "jsonrpc": "2.0",
  "id": <request-id>,
  "error": {
    "code": -32000,
    "message": "Validation failed: invalid_key",
    "data": {
      "reason": "invalid_key"
    }
  }
}

Common reasons:

• invalid_key: API key is invalid or doesn't match stored hash
• unregistered: Client is not registered in the database
• suspended: Client status is suspended
• timeout: Validation endpoint did not respond in time
• network_error: Cannot connect to critique-api

Solutions:

• Verify your API key is correct
• Check that your client is registered and active
• Ensure critique-api is running and accessible
• Check network connectivity

Gateway Connection Failures

If the wrapper cannot connect to the gateway:

{
  "jsonrpc": "2.0",
  "id": <request-id>,
  "error": {
    "code": -32603,
    "message": "Request failed: <error-details>"
  }
}

Solutions:

• Verify the gateway URL is correct
• Check network connectivity to the gateway
• Ensure the gateway is running and accessible

Security Considerations

• API Key Storage: API key is read from environment variables (not command line arguments) to avoid exposure in process lists
• API Key Injection: API key is injected into HTTP headers (not logged or exposed in error messages)
• Fail-Closed Policy: If validation fails or critique-api is unavailable, the wrapper blocks the initialize call
• Defense in Depth: Multiple validation layers ensure security even if one layer is bypassed

Known Limitations

Cursor MCP Client Issue with Null IDs

Issue: Cursor's MCP client sends initialize requests with id: null (which in JSON-RPC 2.0 indicates a notification that doesn't expect a response). However, MCP protocol requires initialize to always receive a response. When the wrapper sends a response with a generated ID (since null is not valid in responses), Cursor logs an error: "Received a response for an unknown message ID".

Status: This is a known limitation in Cursor's MCP client implementation. The wrapper is working correctly according to MCP protocol - the issue is with how Cursor handles initialize requests with null IDs.

Workaround: Despite the error message, the connection may still work. If you encounter issues, please report this to Cursor's support team.

Technical Details:

• Cursor sends: {"jsonrpc":"2.0","id":null,"method":"initialize",...}
• Wrapper must send response (MCP requirement)
• Wrapper generates ID (e.g., "cursor-1") since null is invalid in responses
• Cursor rejects response because ID doesn't match original null

Troubleshooting

Wrapper Not Found

If npx cannot find the package:

# Clear npx cache
npx clear-npx-cache

# Or use specific version
npx -y @critique-mcp/mcp-gateway-wrapper@0.1.0 <gateway-url>

Validation Endpoint Not Responding

If you see timeout errors:

• Check that critique-api is running: curl http://localhost:8000/health
• Verify CRITIQUE_API_URL is correct
• Check firewall/network settings

Gateway Not Responding

If gateway requests fail:

• Verify the gateway URL is correct
• Check that the gateway pod is running (if using Kubernetes)
• Verify network connectivity to the gateway

Development

Local Development

To test the wrapper locally:

# Set environment variables
export CLIENT_API_KEY="your-api-key"
export CRITIQUE_API_URL="http://localhost:8000"

# Run the wrapper
node index.js http://localhost:8080/mcp

Testing with MCP Client

• Configure the wrapper in your MCP client settings
• Restart your MCP client
• Check client logs for any errors
• Verify that tool calls work correctly

License

MIT

Support

For issues and questions, please open an issue in the Critique repository.