Claude Code MCP Integration Setup

Complete guide to enable mcp-gograb-ai in Claude Code extension without affecting Cursor

🔌 Claude Code MCP Integration Setup

Enable mcp-gograb-ai natively in Claude Code extension (running inside Cursor) without breaking Cursor's MCP integration.

🎯 Overview

What This Achieves

✅ Claude Code extension can use MCP tools natively (preflight, log_decision, find_similar, etc.)
✅ Cursor's native MCP continues working unchanged
✅ Zero conflicts - separate configuration files
✅ Platform detection - server automatically knows which platform is calling
✅ Shared learning - both platforms contribute to the same decision database

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    MULTI-PLATFORM MCP                        │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  Cursor Native MCP          Claude Code Extension           │
│  ~/.cursor/mcp.json         .claude/mcp.json                │
│         │                           │                        │
│         └───────────┬───────────────┘                        │
│                     │                                        │
│              MCP Server (stdio)                              │
│       MCP/mcp-development-ai/src/server.ts                   │
│                     │                                        │
│              Platform Detection                              │
│         (CURSOR_AGENT vs CLAUDE_CODE_AGENT)                  │
│                     │                                        │
│         Unified Decision Database                            │
│         docs/data/decisions/*.json                           │
│                                                              │
└─────────────────────────────────────────────────────────────┘

🚀 Quick Setup (2 minutes)

Option 1: Automated Setup (Recommended)

# From workspace root
yarn setup:claude-code-mcp

# Or directly
./scripts/setup-claude-code-mcp.sh

This automatically:

Creates .claude/ directory in workspace
Configures .claude/mcp.json with correct paths
Adds .claude/ to .gitignore
Preserves any existing MCP servers

Option 2: Manual Setup

Create configuration directory:
```
mkdir -p .claude
```

Create .claude/mcp.json:

{
  "mcpServers": {
    "mcp-gograb-ai": {
      "command": "/absolute/path/to/MCP/mcp-development-ai/start-server.sh",
      "args": [],
      "env": {
        "WORKSPACE_ROOT": "/absolute/path/to/workspace",
        "CLAUDE_CODE_AGENT": "true",
        "MCP_WORKSPACE": "/absolute/path/to/workspace"
      }
    }
  }
}

Add to .gitignore:
```
echo ".claude/" >> .gitignore
```

✅ Verification

Step 1: Open Claude Code

In Cursor, press Cmd+Shift+Escape (or Ctrl+Shift+Escape on Windows/Linux) to open Claude Code.

Step 2: Check MCP Servers

Type /mcp in Claude Code chat to see available MCP servers. You should see:

mcp-gograb-ai (or similar name)

Step 3: Test MCP Tools

Try using an MCP tool:

Can you run preflight({ task: "test MCP integration" })?

Expected response:

Claude Code should call the MCP tool and return results
You should see session context, conventions, and guidance

Step 4: Verify Platform Detection

Check the MCP server logs to confirm platform detection:

# The server should log:
# 🖥️  Platform: claude-code (cursor)

🔧 Configuration Details

Configuration Files

Platform	Configuration File	Scope
Cursor Native	`~/.cursor/mcp.json`	Global (all workspaces)
Claude Code	`.claude/mcp.json`	Workspace-local

Environment Variables

Variable	Purpose	Set By
`CURSOR_AGENT`	Identifies Cursor platform	`setup-mcp.sh` (Cursor)
`CLAUDE_CODE_AGENT`	Identifies Claude Code	`setup-claude-code-mcp.sh`
`WORKSPACE_ROOT`	Workspace path for session detection	Both scripts
`MCP_WORKSPACE`	Alternative workspace identifier	Both scripts

Platform Detection Logic

The MCP server automatically detects which platform is calling:

function detectPlatform() {
  if (process.env.CURSOR_AGENT === 'true') {
    return { type: 'cursor', environment: 'cursor' };
  }
  if (process.env.CLAUDE_CODE_AGENT === 'true') {
    return { type: 'claude-code', environment: 'cursor' };
  }
  // ... other platforms
}

📊 How It Works

Shared Learning System

Both Cursor and Claude Code contribute to the same decision database:

Decision Logging:
- Cursor logs decision → docs/data/decisions/cursor_*.json
- Claude Code logs decision → docs/data/decisions/claude-code_*.json
Decision Retrieval:
- Both platforms query the same database
- preflight() returns decisions from all platforms
- find_similar() searches across all platforms
Platform Analytics:
- Track which platform made which decisions
- Compare success rates across platforms
- Identify platform-specific patterns

Session Detection

The MCP server detects the current session from:

sessions/active.json (auto-generated cache)
sessions/sessions-history/{workspace}/history.json (source of truth)
Falls back to workspace name if no session found

🐛 Troubleshooting

Issue: Claude Code doesn't see MCP server

Solution 1: Reload Cursor window

Cmd+Shift+P → Developer: Reload Window

Solution 2: Verify configuration file exists

cat .claude/mcp.json

Solution 3: Check file permissions

ls -la .claude/
# Should show mcp.json with read permissions

Issue: MCP tools return errors

Solution 1: Check MCP server logs

# Look for startup errors in Cursor's Output panel
# View → Output → Select "MCP: mcp-gograb-ai"

Solution 2: Verify workspace path

# In .claude/mcp.json, ensure paths are absolute
# Use full paths like /Users/username/... not relative paths

Solution 3: Test MCP server directly

# Run the server manually to see errors
./MCP/mcp-development-ai/start-server.sh

Issue: Conflicts with Cursor's MCP

This should never happen because:

Cursor uses ~/.cursor/mcp.json (global)
Claude Code uses .claude/mcp.json (workspace-local)
Different configuration files = no conflicts

If you see conflicts:

Check that .claude/mcp.json doesn't exist in ~/.cursor/
Verify Cursor's config is in ~/.cursor/mcp.json
Restart Cursor completely

📚 Related Documentation

Multi-Platform MCP Integration - Complete architecture guide
MCP Development AI Setup - Cursor setup
Platform AI Training - Training system integration

🎯 What's Next?

After setup, you can:

Use MCP tools in Claude Code:
- preflight({ task: "your task" }) - Get context before starting
- log_decision({ ... }) - Record architectural decisions
- find_similar({ query: "..." }) - Search past decisions
- get_stats() - View system statistics
Contribute to shared learning:
- All decisions logged from Claude Code benefit Cursor
- All decisions logged from Cursor benefit Claude Code
- Cross-platform pattern recognition
Track platform performance:
- Compare success rates between platforms
- Identify which platform excels at which tasks
- Optimize workflow based on platform strengths

✅ Verification Checklist

.claude/mcp.json exists in workspace root
.claude/ is in .gitignore
Claude Code shows MCP server when typing /mcp
preflight() works in Claude Code
Cursor's native MCP still works
No conflicts or errors in logs

Last Updated: January 8, 2026 (Session 28.1) Status: ✅ Production Ready Tested: macOS (Cursor + Claude Code extension)