@incogniton/mcp

Local stdio MCP server that bridges to the hosted Incogniton MCP endpoint.

It lets any MCP client that speaks stdio — Claude Desktop, Cursor, Windsurf, VS Code (Continue, Cline, …), and others — talk to Incogniton's hosted https://v5api.incogniton.com/mcp HTTP JSON-RPC server using a single Bearer token.

The bridge reads JSON-RPC 2.0 messages from stdin, POSTs them to the hosted endpoint with Authorization: Bearer <token>, and writes the response to stdout. All diagnostics go to stderr only.

Quick start

# Requires Node.js 18+
npx -y @incogniton/mcp --help

Get your MCP token

Generate an MCP token from inside the Incogniton desktop application:

1. Open the Incogniton app.
2. Go to My Account → Settings.
3. Find the MCP Token section and click Generate Token (or Regenerate if you've created one before).
4. Copy the token. It starts with mcp_live_ and is shown only once — store it somewhere safe (a password manager). If you lose it, just regenerate.

Treat the token like a password: anyone with it can drive your Incogniton profiles. Use a separate token per machine/client if you want to be able to revoke them individually.

Configure your MCP client

Claude Desktop / Cursor / Windsurf

Add the server to your client's MCP config (typically claude_desktop_config.json, ~/.cursor/mcp.json, or the equivalent for your client):

{
  "mcpServers": {
    "incogniton": {
      "command": "npx",
      "args": ["-y", "@incogniton/mcp"],
      "env": {
        "INCOGNITON_MCP_TOKEN": "mcp_live_..."
      }
    }
  }
}

Restart the client and the Incogniton tools should appear.

VS Code (Continue, Cline, etc.)

Use whichever MCP config your extension supports. The command/args/env shape is the same as above — just point it at npx -y @incogniton/mcp with the token in env.

Configuration

The bridge accepts configuration via environment variables or CLI flags. Flags always take precedence over environment variables.

| Env var | Flag | Default | Description | | --- | --- | --- | --- | | INCOGNITON_MCP_TOKEN | --token <token> | required | Bearer token. | | INCOGNITON_MCP_URL | --url <url> | https://v5api.incogniton.com/mcp | HTTP endpoint. | | INCOGNITON_MCP_PROTOCOL_VERSION | --protocol-version <ver> | 2026-05-15 | MCP-Protocol-Version header. | | — | --debug | off | Verbose stderr logging. | | — | --health | — | Hit /health and exit. | | — | --version, -v | — | Print package version and exit. | | — | --help, -h | — | Show usage and exit. |

CLI examples

# Help and version
npx -y @incogniton/mcp --help
npx -y @incogniton/mcp --version

# Health check against the default endpoint
npx -y @incogniton/mcp --health

# Health check against a custom endpoint
npx -y @incogniton/mcp --url https://v5api.incogniton.com/mcp --health

# Run with token on the command line (handy for ad-hoc testing)
INCOGNITON_MCP_TOKEN=mcp_live_... npx -y @incogniton/mcp --debug

How it works

MCP client  <-- stdio (JSON-RPC) -->  incogniton-mcp  <-- HTTPS POST -->  v5api.incogniton.com/mcp

For each newline-delimited JSON-RPC message on stdin, the bridge:

1. Parses it as JSON-RPC 2.0.
2. POSTs it to the configured URL with Authorization: Bearer <token>, Content-Type: application/json, and MCP-Protocol-Version: <version>.
3. Writes the response body back to stdout as one line, unless the server responded with 204 No Content (notifications such as notifications/initialized), in which case nothing is written.
4. On transport or HTTP errors, replies with a synthetic JSON-RPC error object to keep the client unblocked.

Diagnostics (parse errors, transport errors, debug traces) are emitted to stderr only — stdout is reserved for MCP protocol traffic.

Troubleshooting

• missing bearer token — set INCOGNITON_MCP_TOKEN or pass --token.
• Node ... does not provide global fetch — install Node.js 18 or newer.
• Client says "no tools" — run npx -y @incogniton/mcp --health to confirm the endpoint is reachable, then run with --debug and check the client's MCP log for handshake errors.
• Auth errors (401/403) — your token is invalid, expired, or revoked. Generate a fresh one in the Incogniton app under My Account → Settings → MCP Token and update INCOGNITON_MCP_TOKEN in your client config. Tokens are scoped to a single Incogniton account.

License

MIT