@soniqcloud/mcp

Connect any MCP-compatible AI client to your SonIQ project.

Supported clients: Claude Code, Cursor, Windsurf, OpenAI Codex CLI, and any client that supports the Model Context Protocol.

How it works

soniq-mcp is a thin stdio process that bridges your local AI client to your SonIQ server:

Claude Code ←─ stdio ─→ soniq-mcp ←─ HTTP ─→ SonIQ server

When your AI client calls a tool (e.g. get_project_summary), the bridge forwards the call to your SonIQ backend, which handles auth, context resolution, and audit logging.

Installation

npm install -g @soniqcloud/mcp

Requires Node.js >= 20.

Configuration

Required environment variables

| Variable | Description | |----------|-------------| | SONIQ_API_KEY | Your SonIQ API key (generate in the SonIQ extension) | | SONIQ_PROJECT_ID | Numeric ID of the project to connect to |

Optional environment variables

| Variable | Default | Description | |----------|---------|-------------| | SONIQ_API_URL | http://localhost:3310 | Base URL of your SonIQ server |

Client configuration

Claude Code

Add to ~/.claude.json (global) or .claude/settings.json (project-scoped):

{
  "mcpServers": {
    "soniq": {
      "command": "soniq-mcp",
      "env": {
        "SONIQ_API_KEY": "your-api-key-here",
        "SONIQ_PROJECT_ID": "42",
        "SONIQ_API_URL": "http://localhost:3310"
      }
    }
  }
}

Or via claude_desktop_config.json for Claude Desktop:

{
  "mcpServers": {
    "soniq": {
      "command": "soniq-mcp",
      "env": {
        "SONIQ_API_KEY": "your-api-key-here",
        "SONIQ_PROJECT_ID": "42"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "soniq": {
      "command": "soniq-mcp",
      "env": {
        "SONIQ_API_KEY": "your-api-key-here",
        "SONIQ_PROJECT_ID": "42",
        "SONIQ_API_URL": "http://localhost:3310"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "soniq": {
      "command": "soniq-mcp",
      "env": {
        "SONIQ_API_KEY": "your-api-key-here",
        "SONIQ_PROJECT_ID": "42",
        "SONIQ_API_URL": "http://localhost:3310"
      }
    }
  }
}

OpenAI Codex CLI

Codex stores config in TOML, not JSON. Add to ~/.codex/config.toml:

[mcp_servers.soniq]
command = "npx"
args = ["-y", "@soniqcloud/mcp@latest"]
env = { SONIQ_API_KEY = "your-api-key-here", SONIQ_PROJECT_ID = "42", SONIQ_API_URL = "http://localhost:3310" }

Or just run npx @soniqcloud/mcp@latest init --api-key=... --project-id=... --client=codex — it merges the block into your existing config.toml without touching other entries.

Codex CLI has no public custom-slash-command path, so /soniq and /augment-all are not installed for Codex; invoke SonIQ tools directly via Codex's MCP tool surface.

Getting your API key

1. Open VSCode with the SonIQ extension installed
2. View → SonIQ → MCP Participants
3. Click "Generate API Key"
4. Copy the key — it is only shown once

Getting your Project ID

Find it in the SonIQ Projects panel, or via the API:

curl http://localhost:3310/api/brain/projects \
  -H "Authorization: Bearer <your-session-token>"

Troubleshooting

SONIQ_API_KEY environment variable is required The key is missing from the env block in your MCP config. Check the config file and that the env vars are spelled correctly.

HTTP 401: Invalid API key The API key is invalid or was revoked. Generate a new one in the SonIQ extension.

HTTP 401: X-Soniq-Project-Id header required SONIQ_PROJECT_ID is not set. Add it to the env block.

Bridge connects but tools return errors Check the SonIQ server is running: curl http://localhost:3310/health. If using a remote server, verify SONIQ_API_URL points to the correct URL.

SSE notifications not working SSE requires eventsource package (bundled as a dependency). If it fails, the bridge continues working but server-push notifications are disabled.

Privacy

• Your API key authenticates to your own SonIQ server
• No credentials are routed through Anthropic or any third party
• All tool calls are logged in your SonIQ audit trail
• BYOK (bring your own keys) — SonIQ never holds your LLM API keys

License

UNLICENSED — private package, not for public distribution.