@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:

1. Wrapper intercepts the initialize call
2. Validates API key by calling POST {CRITIQUE_API_URL}/api/v1/validation/initialize with X-API-Key header
3. If validation fails: Returns MCP error to client, does not forward to gateway
4. 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:

1. First Gate: Wrapper validates initialize call (blocks unauthorized sessions)
2. 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/[email protected] <gateway-url>

Validation Endpoint Not Responding

If you see timeout errors:

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

Gateway Not Responding

If gateway requests fail:

1. Verify the gateway URL is correct
2. Check that the gateway pod is running (if using Kubernetes)
3. 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

1. Configure the wrapper in your MCP client settings
2. Restart your MCP client
3. Check client logs for any errors
4. Verify that tool calls work correctly

License

MIT

Support

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