MCP clients

Model Context Protocol is how editors and assistants connect to ClawQL. ClawQL Core — search, execute, audit, cache — has no opt-out. Hosts register ingest_external_knowledge and memory_ingest / memory_recall by default (set CLAWQL_ENABLE_MEMORY=0 to hide vault memory tools). Optional tools include sandbox_exec (CLAWQL_ENABLE_SANDBOX=1), notify (CLAWQL_ENABLE_NOTIFY, Slack chat.postMessage; Slack notify) and knowledge_search_onyx (CLAWQL_ENABLE_ONYX, Onyx when onyx is in the merge; Onyx knowledge search). Cursor and Claude Desktop are common hosts.

What is MCP?

The MCP server runs as a subprocess (stdio) or over the network (HTTP). Your client configuration supplies environment variables such as spec paths or CLAWQL_PROVIDER. Single-spec execute uses in-process OpenAPI→GraphQL; no separate GraphQL service is required.

stdio (npm)

Use npx with -p clawql-mcp so the binary resolves from the package:

{
  "mcpServers": {
    "clawql": {
      "command": "npx",
      "args": ["-p", "clawql-mcp", "clawql-mcp"],
      "env": {
        "CLAWQL_SPEC_PATH": "/absolute/path/to/openapi.yaml"
      }
    }
  }
}

stdio (git checkout)

{
  "mcpServers": {
    "clawql": {
      "command": "node",
      "args": ["/absolute/path/to/ClawQL/dist/server.js"],
      "env": {
        "CLAWQL_SPEC_PATH": "/absolute/path/to/openapi.yaml"
      }
    }
  }
}

For development you can run tsx against src/server.ts instead; ensure the repo is built for production-style runs.

Streamable HTTP

For clawql-mcp-http, Docker, Kubernetes, or Cloud Run, configure your client with a url (not command). Copy .cursor/mcp.json.example to .cursor/mcp.json and set the base URL your deployment exposes. See Deployment. For managed Tailscale or Headscale MagicDNS, CLAWQL_MCP_URL, and ${env:…} in mcp.json, see Tailscale & Headscale. GraphQL debugging is available at /graphql on the same origin.

Gateway API key auth

HTTP MCP can enforce an API key on /mcp routes via clawql-auth. Upstream provider credentials (AWS SigV4, env JSON) live in the same package.

export CLAWQL_AUTH_MODE=apiKey
export CLAWQL_API_KEY="your-long-random-secret"

Clients must send Authorization: Bearer <CLAWQL_API_KEY> (or X-API-Key) on Streamable HTTP MCP requests.

OIDC/SAML login flows and RBAC/ABAC are roadmap — see packages/clawql-auth/README.md and .env.example (CLAWQL_AUTH_*).

Presidio redaction

When enabled, text is redacted before persistence on execute responses, memory_ingest, and ingest_external_knowledge:

export CLAWQL_ENABLE_PRESIDIO=1
export CLAWQL_PRESIDIO_ANALYZER_URL=http://presidio-analyzer:3000
export CLAWQL_PRESIDIO_ANONYMIZER_URL=http://presidio-anonymizer:3000
# Optional: block when Presidio is unreachable
export CLAWQL_PRESIDIO_FAILURE_POLICY=block

Tier 1 Compose with Presidio:

cd examples/clawql-local-docker-compose
docker compose -f docker-compose.yml -f docker-compose.presidio.override.yml up -d

Full mandatory IDP-hop redaction remains roadmap — Security · mcp-tools.md.

OpenClaw

To use the OpenClaw CLI (npm install -g openclaw) as an MCP host for ClawQL — openclaw mcp set, HTTP vs stdio, env — see OpenClaw + ClawQL and the canonical repo guide docs/openclaw/using-openclaw-with-clawql.md.