@sigilcore/mcp-proxy

Wraps MCP tool connections in Sigil Intent Attestations. Every tool call is evaluated against your operator's warranty.md policy before it reaches the real MCP server.

Quick Start

# Install
npm install -g @sigilcore/mcp-proxy

# Wrap any MCP server
npx @sigilcore/mcp-proxy -- npx @some/mcp-server

# Set your API key
export SIGIL_API_KEY=sk_sigil_YOUR_KEY

MCP Client Config

Change one line in your MCP client config:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["@sigilcore/mcp-proxy", "--", "npx", "@some/pg-mcp"]
    }
  }
}

Configuration

Generate a starter config: npx @sigilcore/mcp-proxy --init

Precedence: CLI flags > environment variables > config file > defaults.

| CLI Flag | Env Var | Config Key | Default | |---|---|---|---| | --key | SIGIL_API_KEY | (env only) | (required) | | --sign-url | SIGIL_SIGN_URL | signUrl | https://sign.sigilcore.com | | --log-level | SIGIL_LOG_LEVEL | logLevel | info | | --server-id | — | serverId | derived from command/URL | | --server-name | — | serverName | same as serverId | | --pending-timeout | SIGIL_PENDING_TIMEOUT | pendingTimeout | 30000 | | --unsafe-bypass | (CLI only) | (CLI only) | false | | --remote | — | — | — | | --port | — | — | auto |

Server Identity

• serverId — Binding identity (security-critical). Used in txCommit preimage and policy evaluation. Auto-derived from the package name (stdio) or full URL (HTTP) if not set.
• serverName — Display label (logs only). Defaults to serverId.

Unsafe Bypass

The proxy is fail-closed by default. When Sign is unreachable, tool calls are blocked.

To allow ungoverned calls during Sign outages, use the --unsafe-bypass CLI flag. This flag is intentionally not available as an env var or config file option — it must be visible in your MCP client config:

npx @sigilcore/mcp-proxy --unsafe-bypass -- npx @some/mcp-server

Every bypassed call emits an ungoverned_tool_call error-level log. Auth failures (401) are NEVER bypassed.

HTTP/SSE Transport

Proxy a remote MCP server:

npx @sigilcore/mcp-proxy --remote https://api.example.com/mcp

Upstream Authentication

Remote MCP servers often require auth. Configure upstream headers in your config file using environment variable references:

{
  "upstream": {
    "headers": {
      "Authorization": "Bearer $UPSTREAM_TOKEN",
      "X-Custom-Header": "$CUSTOM_HEADER_VALUE"
    }
  }
}

All header values must reference at least one $IDENTIFIER env var. Raw secrets are rejected at load time.

Convenience shortcut for Authorization header:

export SIGIL_UPSTREAM_AUTH="Bearer sk-abc123..."
npx @sigilcore/mcp-proxy --remote https://api.example.com/mcp

Extractors

Map tool arguments to Sigil policy fields in sigil.config.json:

{
  "extractors": {
    "fetch": { "url": "url" },
    "write_file": { "path": "path" }
  }
}

Error Codes

• -32001 — Sigil policy denial (DENIED, fail-closed, hold timeout)
• -32002 — Sigil authentication failure (invalid API key)

License

MIT