Skip to main content

Installation

This guide walks you through setting up the recapt MCP server in your AI coding assistant.

Prerequisites​

  • Node.js 18+ installed on your machine
  • Recapt account with session recording set up
  • MCP key from your recapt dashboard

Getting Your MCP Key​

  1. Go to dash.recapt.app/settings
  2. Navigate to the MCP Keys tab
  3. Click Create New Key
  4. Copy the key (starts with mcp_sk_)
Keep your key secure

Your MCP key provides access to your behavioral data. Don't commit it to version control or share it publicly.

The easiest way to set up the MCP server is with the interactive setup wizard:

npx @recapt/cli setup

This will:

  1. Detect which AI IDEs you have installed
  2. Prompt you for your MCP key
  3. Configure the selected IDEs automatically
  4. Optionally install workflow skills

After setup, restart your IDE to activate the MCP server.

Manual Setup​

If you prefer to configure manually, add the recapt server to your IDE's MCP configuration.

Cursor​

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

{
  "mcpServers": {
    "recapt": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@recapt/mcp@latest"],
      "env": {
        "RECAPT_SECRET_KEY": "mcp_sk_your_key_here"
      }
    }
  }
}

Claude Code​

Add to ~/.claude.json (global) or .mcp.json (project):

{
  "mcpServers": {
    "recapt": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@recapt/mcp@latest"],
      "env": {
        "RECAPT_SECRET_KEY": "mcp_sk_your_key_here"
      }
    }
  }
}

Windsurf​

Add to ~/.windsurf/mcp.json (global) or .windsurf/mcp.json (project):

{
  "mcpServers": {
    "recapt": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@recapt/mcp@latest"],
      "env": {
        "RECAPT_SECRET_KEY": "mcp_sk_your_key_here"
      }
    }
  }
}

VS Code​

Add to .vscode/mcp.json in your project:

{
  "servers": {
    "recapt": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@recapt/mcp@latest"],
      "env": {
        "RECAPT_SECRET_KEY": "mcp_sk_your_key_here"
      }
    }
  }
}

Zed​

Add to ~/.config/zed/settings.json (global) or .zed/settings.json (project):

{
  "context_servers": {
    "recapt": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@recapt/mcp@latest"],
      "env": {
        "RECAPT_SECRET_KEY": "mcp_sk_your_key_here"
      }
    }
  }
}

Codex CLI​

Add to ~/.codex/config.toml (global) or .codex/config.toml (project):

[mcp_servers.recapt]
type = "stdio"
command = "npx"
args = ["-y", "@recapt/mcp@latest"]

[mcp_servers.recapt.env]
RECAPT_SECRET_KEY = "mcp_sk_your_key_here"

GitHub Copilot​

Add to .github/mcp.json in your project:

{
  "servers": {
    "recapt": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@recapt/mcp@latest"],
      "env": {
        "RECAPT_SECRET_KEY": "mcp_sk_your_key_here"
      }
    }
  }
}

Installing Skills​

Skills are guided workflows that help your AI assistant tackle complex tasks. We recommend installing the self-improvement skill:

npx @recapt/cli skill install self-improvement

This creates an AGENTS.md file in your project that guides your AI through the full self-improvement workflow.

Available skills:

  • self-improvement: End-to-end issue detection, fixing, and validation
  • regression-hunt: Find what broke after a deployment
  • deep-dive: Comprehensive page or flow analysis

Install all skills at once:

npx @recapt/cli skill install --all

List available skills:

npx @recapt/cli skill list

Verifying Installation​

After restarting your IDE, test the connection by asking your AI assistant:

What domains are configured in recapt?

If configured correctly, the AI will list your tracked domains.

You can also try:

Run a diagnostic on my site

This will analyze your site and show any detected UX issues.

Troubleshooting​

"API not configured" error​

Make sure your RECAPT_SECRET_KEY is set correctly in the MCP configuration. The key should start with mcp_sk_.

MCP server not appearing​

  1. Ensure you've restarted your IDE after configuration
  2. Check that the config file is valid JSON
  3. Verify the file is in the correct location for your IDE

No data returned​

Make sure you have:

  1. The recapt script installed on your website
  2. Session recordings being captured
  3. At least a few days of data for meaningful analysis

Next Steps​