MCP Configure¶

canviq mcp configure registers Canviq as an MCP server in the config files for Claude Code and Cursor. After running it, those tools can call Canviq APIs through natural language.

Run the command¶

canviq mcp configure

The command checks for ~/.claude/ and ~/.cursor/ directories. For each one it finds, it merges the Canviq server entry into the tool's config file.

Claude Code writes to ~/.claude/settings.json.

Cursor writes to ~/.cursor/mcp.json.

What it writes¶

The command adds this entry under mcpServers:

{
  "mcpServers": {
    "canviq": {
      "url": "https://canviq.app/api/mcp/tools",
      "headers": {
        "Authorization": "Bearer ${CANVIQ_API_KEY}"
      }
    }
  }
}

${CANVIQ_API_KEY} is written as a literal string. The command does not substitute your actual key. Claude Code and Cursor read the CANVIQ_API_KEY environment variable at launch time and substitute it when making requests. This prevents your API key from being committed if the config file lands in a dotfiles repo.

Set the environment variable¶

After running the command, add your API key to your shell profile:

# ~/.zshrc or ~/.bashrc
export CANVIQ_API_KEY=pk_live_...

The key must be agent-backed, generated from Settings → Agents (/admin/settings/agents). An SDK key or a key created via the generic API Keys wizard shares the same pk_live_/pk_test_ prefix but is not linked to an agent; Claude Code or Cursor will connect but every tool call will fail with an auth error. See Getting an agent-backed key.

Reload your profile or restart your terminal:

source ~/.zshrc

Preview the config without writing¶

Use --print to see the config block without touching any files:

canviq mcp configure --print

This is useful for manual configuration or to verify what would be written.

Manual configuration¶

If neither ~/.claude/ nor ~/.cursor/ exists, the command prints the config block and instructions. Copy the output into your tool's MCP server list by hand.

Verify the connection¶

After restarting Claude Code or Cursor, run a natural language query to confirm the integration works:

List my Canviq surveys

If the tool returns a list of surveys, the MCP server is configured. If it returns an auth error, confirm that CANVIQ_API_KEY is set in the environment where the tool launches.

!!! note Some tools read shell profiles only from login shells. If your key is set in ~/.zshrc but the tool launches from a GUI, you may need to set CANVIQ_API_KEY in the tool's own environment settings instead.

Global flags¶

canviq mcp configure accepts the global --json and --quiet flags without erroring, but ignores both. It always prints the same plain-text output (or writes config files) regardless; use --print above to change what it does. See Scripting and CI for the full global-flags contract.