Client compatibility

Verified MCP client configuration shapes for secure-mcp 2.x, which requires protocol revision 2026-07-28 and rejects legacy handshakes.

Protocol requirement

secure-mcp 2.x is a strict MCP v2 server: it serves protocol revision 2026-07-28 over stdio and rejects legacy 2025-era initialize openings. Do not use this server with a client that cannot negotiate 2026-07-28. The repository’s protocol tests verify the server against the official MCP SDK v2 client; client-side support is controlled by each client’s release.

The config shapes below follow each client’s current official documentation and use absolute paths. SECURE_MCP_ALLOWED_ROOTS is always required.

OpenAI Codex

Codex stores MCP configuration in ~/.codex/config.toml (or a trusted project .codex/config.toml). The installer writes this table:

[mcp_servers.secure-mcp]
command = "node"
args = ["/absolute/path/to/secure-mcp/dist/index.js"]

[mcp_servers.secure-mcp.env]
SECURE_MCP_ALLOWED_ROOTS = "/absolute/path/to/repositories"

Reference: OpenAI Codex MCP documentation.

Cursor

Cursor reads global ~/.cursor/mcp.json or project .cursor/mcp.json. Stdio entries use command, args, and env:

{
  "mcpServers": {
    "secure-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/secure-mcp/dist/index.js"],
      "env": {
        "SECURE_MCP_ALLOWED_ROOTS": "/absolute/path/to/repositories"
      }
    }
  }
}

Reference: Cursor MCP documentation.

Claude Desktop

Claude Desktop reads claude_desktop_config.json (~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows):

{
  "mcpServers": {
    "secure-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/secure-mcp/dist/index.js"],
      "env": {
        "SECURE_MCP_ALLOWED_ROOTS": "/absolute/path/to/repositories"
      }
    }
  }
}

Reference: MCP connect to local servers.

Claude Code

Add a local stdio server with:

claude mcp add --transport stdio secure-mcp -- node /absolute/path/to/secure-mcp/dist/index.js

Or use a .mcp.json with the mcpServers shape above. Project .mcp.json servers require workspace trust before they connect. Reference: Claude Code MCP documentation.

VS Code / GitHub Copilot

VS Code reads .vscode/mcp.json for repository-scoped servers or the user settings.json for personal configuration. It uses a top-level servers key, not mcpServers:

{
  "servers": {
    "secure-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/secure-mcp/dist/index.js"],
      "env": {
        "SECURE_MCP_ALLOWED_ROOTS": "/absolute/path/to/repositories"
      }
    }
  }
}

Reference: GitHub Docs: use MCP in your IDE.

pi

pi reads ~/.pi/agent/mcp.json. The installer writes the mcpServers entry plus the pi fields that expose canonical tool names:

{
  "mcpServers": {
    "secure-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/secure-mcp/dist/index.js"],
      "env": {
        "SECURE_MCP_ALLOWED_ROOTS": "/absolute/path/to/repositories"
      },
      "lifecycle": "lazy",
      "directTools": true,
      "toolPrefix": "none"
    }
  }
}

Grok Build TUI (unsupported)

Grok is not supported until it speaks MCP protocol revision 2026-07-28. Current Grok Build TUI sessions request 2025-11-25 and open with initialize. This server answers that opening with the SDK unsupported-protocol-version error (-32022) and does not fall back. The installer does not write ~/.grok/config.toml. Do not add a Grok MCP entry until the client negotiates 2026-07-28 via server/discover.

Generic stdio clients

Any stdio MCP client that negotiates protocol revision 2026-07-28 can connect to node /absolute/path/to/secure-mcp/dist/index.js with SECURE_MCP_ALLOWED_ROOTS set. The client must open with server/discover; the server rejects claim-less initialize openings with the unsupported-protocol-version error.