Claude Desktop Custom Connector Setup

Session: 79 | Last Updated: February 1, 2026

Overview

Claude Desktop now supports Custom Connectors (Beta) that enable native MCP tool integration over HTTP. This allows Claude Desktop (Cowork) to connect directly to our GoGrab AI backend and use all 79+ MCP tools without browser automation.

Quick Setup

1. Start the Backend

cd apis/backend-ai-api
yarn start:dev
# or
npm run start:dev

Backend runs on port 3000 (or 3001 depending on config).

2. Add Custom Connector in Claude Desktop

1. Open Claude Desktop
2. Go to Settings → Connectors
3. Click "Add custom connector"
4. Configure:
   • Name: GoGrab AI
   • URL: http://localhost:3000/ai-api/mcp
   • Advanced Settings: (leave default for local)

3. Verify Connection

After adding, Claude Desktop should:

1. Send initialize request
2. Request tools/list
3. Display 79+ tools in the tool picker

Endpoints

Main JSON-RPC Endpoint

URL: POST /ai-api/mcp or POST /ai-api/mcp/jsonrpc

All MCP protocol messages go through this endpoint.

Server-Sent Events (SSE)

URL: GET /ai-api/mcp/events?agentId=xxx

For real-time notifications (handoff completion, etc.)

MCP Protocol Methods

Tool Categories (79 Tools)

Handoff Tools (Session 79)

These tools enable Cowork to participate in the multi-agent handoff system:

check_handoffs

Check for pending handoffs assigned to you.

{
  "method": "tools/call",
  "params": {
    "name": "check_handoffs",
    "arguments": {
      "agentId": "cowork-claude-desktop-xxx",
      "workspace": "editor2"
    }
  }
}

accept_handoff

Accept a handoff before starting work.

{
  "method": "tools/call",
  "params": {
    "name": "accept_handoff",
    "arguments": {
      "handoffId": "handoff-123",
      "agentId": "cowork-claude-desktop-xxx"
    }
  }
}

complete_handoff

Mark a handoff as complete with results.

{
  "method": "tools/call",
  "params": {
    "name": "complete_handoff",
    "arguments": {
      "handoffId": "handoff-123",
      "agentId": "cowork-claude-desktop-xxx",
      "response": "Tested login flow successfully. All 5 test cases passed."
    }
  }
}

Authentication

Local Development

No authentication required for localhost connections.

Production

Use API key authentication:

POST /ai-api/mcp
X-MCP-API-Key: mcp_your_api_key
X-MCP-Project-Id: your-project-id

Recommended Workflow

1. Initialize: Claude Desktop auto-registers as a Cowork agent
2. Preflight: Call preflight before any task to get context
3. Check Handoffs: Periodically call check_handoffs during idle time
4. Accept: When you get a handoff, call accept_handoff
5. Work: Complete the assigned tasks
6. Complete: Call complete_handoff with results
7. Log: Use log_decision for important decisions

Troubleshooting

"Connection refused"

• Ensure backend is running: yarn start:dev
• Check port (3000 or 3001)
• Verify URL format: http://localhost:3000/ai-api/mcp

"Tools not discovered"

• Check Claude Desktop logs for error details
• Verify /tools/list returns tools via curl:

  curl -X POST http://localhost:3000/ai-api/mcp/jsonrpc \
    -H "Content-Type: application/json" \
    -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
  

"Agent not registered"

• Check backend logs for registration errors
• Verify AgentService is available in module

Protocol Reference

Request Format (JSON-RPC 2.0)

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "preflight",
    "arguments": {
      "task": "Analyze authentication flow"
    }
  },
  "id": 1
}

Response Format

Success:

{
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "..."
      }
    ]
  },
  "id": 1
}

Error:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32602,
    "message": "Missing required parameter: name"
  },
  "id": 1
}

Related Documentation

• Cowork Integration Limitations
• MCP Reference
• Multi-Agent Roadmap

Session 79 - Claude Desktop Connector Integration