CartoGopher

Set up CartoGopher — AI-native code intelligence that gives you 30+ tools for navigating codebases with 94% fewer tokens than file reading.

When to Use This Skill

Use this skill when the user wants to:

• Set up CartoGopher for their project
• Get a CartoGopher trial API key
• Configure the CartoGopher MCP server
• Improve code navigation and understanding with AI-native tooling

What CartoGopher Does

CartoGopher parses a codebase into a compact graph (bake.json) and exposes 30+ MCP tools:

• Symbol lookup — find functions, types, and their relationships
• API tracing — trace endpoints from frontend to database
• Architecture mapping — understand project structure and get placement suggestions
• AST-aware search — search code semantically, not just text matching
• Frontend analysis — Vue, React component analysis with props, hooks, store usage

Setup Flow

Step 1: Get a Trial API Key

Ask the user for their email address, then request a 7-day trial key:

curl -s -X POST https://cartogopher.com/api/agent-trial \
  -H 'Content-Type: application/json' \
  -d '{"email":"USER_EMAIL_HERE"}'

The response will contain:

{
  "success": true,
  "api_key": "cg_agent_...",
  "trial_ends_at": "2026-02-27T...",
  "message": "Trial started! Configure your MCP server with this key."
}

Save the api_key value — you'll need it for the next steps.

If the response contains an error:

• "Disposable email addresses are not allowed" — ask for a real email
• "A trial already exists for this email" — the user already has a key, ask them to check their email or provide the existing key
• "Rate limit exceeded" — wait and retry later

Step 2: Verify the Key Works

curl -s -X POST https://cartogopher.com/api/verify-key \
  -H 'Content-Type: application/json' \
  -d '{"api_key":"API_KEY_HERE"}'

Step 3: Install the MCP Server

Download and install the CartoGopher bundle for the user's platform. Each download is a zip containing the binary, MCP server, and dependencies.

Container prerequisite (Linux/Docker only): CartoGopher requires /etc/machine-id to exist. Most Linux desktops have this, but containers often don't:

# Ensure machine-id exists (required in containers)
[ -f /etc/machine-id ] || (cat /proc/sys/kernel/random/uuid | tr -d '-' > /etc/machine-id)

Detect platform and download:

# Detect platform and set download URL
PLATFORM=$(uname -s)-$(uname -m)

case "$PLATFORM" in
  Darwin-arm64)  DOWNLOAD_URL="https://cartogopher.com/downloads/cartogopher/v4/mac/arm64" ;;
  Darwin-x86_64) DOWNLOAD_URL="https://cartogopher.com/downloads/cartogopher/v4/mac/intel" ;;
  Linux-x86_64)  DOWNLOAD_URL="https://cartogopher.com/downloads/cartogopher/v4/linux/amd64" ;;
  Linux-aarch64) DOWNLOAD_URL="https://cartogopher.com/downloads/cartogopher/v4/linux/arm64" ;;
  *) echo "Unsupported platform: $PLATFORM"; exit 1 ;;
esac

# Download, extract, and clean up
curl -sL "$DOWNLOAD_URL" -o cg.zip && unzip cg.zip -d ~/.cartogopher/mcp-server && rm cg.zip

Platform-specific one-liners (if you already know the platform):

• macOS Apple Silicon (M1/M2/M3/M4):

  curl -sL https://cartogopher.com/downloads/cartogopher/v4/mac/arm64 -o cg.zip && unzip cg.zip -d ~/.cartogopher/mcp-server && rm cg.zip
  

• macOS Intel:

  curl -sL https://cartogopher.com/downloads/cartogopher/v4/mac/intel -o cg.zip && unzip cg.zip -d ~/.cartogopher/mcp-server && rm cg.zip
  

• Linux amd64:

  curl -sL https://cartogopher.com/downloads/cartogopher/v4/linux/amd64 -o cg.zip && unzip cg.zip -d ~/.cartogopher/mcp-server && rm cg.zip
  

• Linux arm64:

  curl -sL https://cartogopher.com/downloads/cartogopher/v4/linux/arm64 -o cg.zip && unzip cg.zip -d ~/.cartogopher/mcp-server && rm cg.zip
  

After extraction, install the MCP server dependencies:

cd ~/.cartogopher/mcp-server
npm install

Step 4: Set the API Key Permanently

The API key MUST be set in the user's shell profile so the MCP server process can access it. Setting it with export in a single session is NOT sufficient — MCP servers run as separate processes.

# Detect shell profile
SHELL_PROFILE="$HOME/.zshrc"
[ -f "$HOME/.bashrc" ] && [ ! -f "$HOME/.zshrc" ] && SHELL_PROFILE="$HOME/.bashrc"

# Add API key to shell profile (only if not already present)
if ! grep -q "CARTOGOPHER_API_KEY" "$SHELL_PROFILE" 2>/dev/null; then
  echo "export CARTOGOPHER_API_KEY=API_KEY_HERE" >> "$SHELL_PROFILE"
fi

source "$SHELL_PROFILE"

Step 5: Configure the MCP Server

The MCP configuration depends on which AI tool the user runs:

For OpenClaw (openclaw.json):

{
  "mcpServers": {
    "cartogopher": {
      "command": "node",
      "args": ["~/.cartogopher/mcp-server/cartogopher-mcp.js"],
      "env": {
        "CURSOR_WORKSPACE": ".",
        "CARTOGOPHER_API_KEY": "API_KEY_HERE"
      }
    }
  }
}

For Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "cartogopher": {
      "command": "node",
      "args": ["~/.cartogopher/mcp-server/cartogopher-mcp.js"],
      "env": {
        "CURSOR_WORKSPACE": "${workspaceFolder}",
        "CARTOGOPHER_API_KEY": "API_KEY_HERE"
      }
    }
  }
}

For Claude Code:

claude mcp add cartogopher node ~/.cartogopher/mcp-server/cartogopher-mcp.js \
  -e CURSOR_WORKSPACE=. \
  -e CARTOGOPHER_API_KEY=API_KEY_HERE

Step 6: Verify Setup

After configuration, test that the MCP tools are working by calling the shake tool on the user's project. If it returns a project overview, setup is complete.

Important Notes

• Trial keys have a cg_agent_ prefix and last 7 days
• Trial allows 2 devices simultaneously
• The MCP server must have CARTOGOPHER_API_KEY explicitly in its env config — it does NOT inherit from the shell
• After setup, the user must restart their AI tool (Cursor, Claude, etc.) for MCP changes to take effect
• If the user already has a CartoGopher API key (cg_live_ or cg_trial_), skip the trial step and go straight to MCP configuration