Skip to content

HTTP Mode

The server can run in streamable-http mode in addition to stdio.

Behavior

  • MCP endpoint: /mcp
  • Discovery endpoint: /.well-known/mcp-server
  • Optional bearer-token auth
  • Optional /metrics endpoint when KICAD_MCP_ENABLE_METRICS=true
  • Optional OpenTelemetry OTLP export when OTEL_EXPORTER_OTLP_ENDPOINT is set or --telemetry is passed
  • Optional CORS allowlist using explicit http://, https://, or vscode-webview:// origins only
  • Wildcard CORS (*) is rejected intentionally
  • Stateless HTTP by default, with opt-in stateful HTTP for session-aware clients
  • Legacy /sse and /messages routes stay disabled unless KICAD_MCP_LEGACY_SSE=true

The default HTTP port is 3334. For KiCad Studio local bridge setups, 27185 is a good convention if you want a dedicated port.

Stateless mode is the ChatGPT-compatible default. In this mode the initialize response does not include Mcp-Session-Id, and follow-up requests such as tools/list must work without a session header. Set KICAD_MCP_STATEFUL_HTTP=true only for clients that preserve Mcp-Session-Id from the initialize response and send it on subsequent Streamable HTTP requests.

Environment Variables

  • KICAD_MCP_TRANSPORT=http
  • KICAD_MCP_HOST=127.0.0.1
  • KICAD_MCP_PORT=3334
  • KICAD_MCP_CORS_ORIGINS=https://app.example.com,http://127.0.0.1:3334
  • KICAD_MCP_AUTH_TOKEN=...
  • KICAD_MCP_STATEFUL_HTTP=true
  • KICAD_MCP_ENABLE_METRICS=true
  • KICAD_MCP_LEGACY_SSE=true
  • OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318
  • OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
  • OTEL_SERVICE_NAME=kicad-mcp-pro

Discovery, Metrics, and Token Rotation

  • GET /.well-known/mcp-server returns the server card plus capabilities.toolCategories, capabilities.profiles, and capabilities.experimentalTools so clients can negotiate a profile before listing tools.
  • GET /metrics emits in-memory Prometheus text metrics for tool calls and sliding-window p50/p95 latency when metrics are enabled.
  • OpenTelemetry emits MCP request, tool, KiCad CLI, and PCB parser spans plus tool/session/CLI metrics to the configured OTLP collector. Attributes do not include project paths, board contents, schematic contents, request arguments, CLI output, or collector headers.
  • POST /.well-known/mcp-server/token-rotate rotates the in-memory bearer token. The request must authenticate with the current token and send JSON like {"new_token": "..."}.

Notes

  • When bearer auth is enabled, cross-origin POST /mcp requests are checked against KICAD_MCP_CORS_ORIGINS.
  • If you run over stdio, KICAD_MCP_AUTH_TOKEN is ignored and a startup warning is emitted.
  • Use explicit origins instead of wildcard origins so the allowlist stays valid and auditable.
  • Token rotation is intentionally in-memory; update your environment or TOML config separately for persistence.