Session 79: Claude Desktop Connector Integration

Date: February 1, 2026 Initiated by: Cowork Agent (Claude Desktop) Status: Planning Complete - Ready for Implementation Priority: HIGH

Executive Summary

Claude Desktop now supports Custom Connectors (Beta) with Remote MCP server URLs. This is the breakthrough we've been waiting for. We can potentially connect Claude Desktop directly to our backend-ai-api MCP Gateway, enabling native tool calling without the browser tab bridge workaround.

This session's goal: Validate the connector protocol, implement necessary backend changes, and establish Cowork as a first-class agent in our multi-agent system.

Strategic Alignment

Short-Term Goal (Reminder)

A perfect standalone system within our platform's parameters where GoGrab devs and users can fully experience a significant life improvement by having access to a real personalized system.

This session contributes: Direct Claude Desktop integration removes the browser automation bottleneck, enabling real-time agent-to-agent communication.

Medium-Term Goal (Reminder)

Full platform/tools autonomy from other platforms (like Claude's Cowork and OpenClaw.ai). All necessary tools for desktop connectivity, browser control, task execution - but within GoGrab Space platform context.

This session contributes: Understanding the connector protocol gives us the blueprint to build our own desktop connectivity layer, reducing dependency on Anthropic's specific implementation.

Long-Term Goal (Reminder)

Full autonomy. Own AI models. Self-dependent. Smart data acquisition and proper infrastructure for future switch.

This session contributes: Every agent interaction, every decision, every handoff generates training data. Native MCP integration means higher-quality data capture vs. brittle browser automation.

Current State Analysis

What Works Today

What's Broken for Cowork

New Opportunity: Custom Connectors (Beta)

Claude Desktop Settings now shows:

• Connectors menu with "Add custom connector"
• "Remote MCP server URL" field
• "Advanced settings" (likely for auth headers)

This suggests Anthropic has implemented MCP-over-HTTP transport.

Technical Investigation Required

Critical Question 1: What protocol does the Custom Connector expect?

Possibilities:

1. MCP Streamable HTTP - JSON-RPC over HTTP with SSE for streaming
2. Standard REST - Simple POST /tools/call (what we have)
3. MCP-over-WebSocket - Full duplex MCP protocol

How to verify:

• Add connector pointing to our endpoint
• Check browser DevTools network tab for request format
• Check Claude Desktop logs for errors

Critical Question 2: What authentication does it support?

Possibilities:

1. No auth (localhost only)
2. Bearer token in Authorization header
3. Custom headers (X-MCP-API-Key)
4. OAuth flow

How to verify:

• Check "Advanced settings" in connector dialog
• Test with different auth configurations

Critical Question 3: Does it support server-initiated events?

Possibilities:

1. No - client must poll
2. Yes - via SSE (Server-Sent Events)
3. Yes - via WebSocket upgrade

Impact: Determines if we can push handoff notifications.

Implementation Plan

Phase 1: Protocol Validation (Day 1)

Owner: Any agent with Claude Desktop access Deliverable: Protocol specification document

Task 1.1: Test Current Endpoint

1. Open Claude Desktop Settings > Connectors
2. Add custom connector:
   - Name: "GoGrab AI Test"
   - URL: http://localhost:3001/ai-api/mcp
3. Start backend-ai-api locally
4. Observe:
   - Does Claude Desktop discover tools?
   - What HTTP requests does it make?
   - What errors appear?

Task 1.2: Capture Protocol Details

1. Use browser DevTools or proxy to capture requests
2. Document:
   - HTTP method (GET/POST)
   - Request format (JSON-RPC vs REST)
   - Expected response format
   - Any handshake/initialization sequence

Task 1.3: Document Findings

Create: session-79/79.1-protocol-validation-results.md
Contents:
- Request/response examples
- Error messages encountered
- Required changes identified

Phase 2: MCP HTTP Gateway (Days 2-3)

Owner: Backend agent (Cursor/Claude Code) Deliverable: MCP-compliant HTTP endpoints

Prerequisite: Phase 1 findings confirm protocol requirements

Task 2.1: Add MCP JSON-RPC Endpoint

If Claude Desktop expects standard MCP JSON-RPC:

// File: apis/backend-ai-api/src/app/mcp-gateway/mcp-http.controller.ts

@Controller('mcp')
export class McpHttpController {

  @Post()
  @Header('Content-Type', 'application/json')
  async handleMcpRequest(@Body() request: McpJsonRpcRequest): Promise<McpJsonRpcResponse> {
    const { jsonrpc, method, params, id } = request;

    switch (method) {
      case 'initialize':
        return this.handleInitialize(params, id);
      case 'tools/list':
        return this.handleToolsList(id);
      case 'tools/call':
        return this.handleToolsCall(params, id);
      case 'resources/list':
        return this.handleResourcesList(id);
      case 'prompts/list':
        return this.handlePromptsList(id);
      default:
        return { jsonrpc: '2.0', error: { code: -32601, message: 'Method not found' }, id };
    }
  }
}

Task 2.2: Map Existing Tools to MCP Format

// Tool list response format
{
  "jsonrpc": "2.0",
  "result": {
    "tools": [
      {
        "name": "preflight",
        "description": "Get context before any task",
        "inputSchema": {
          "type": "object",
          "properties": {
            "task": { "type": "string" }
          },
          "required": ["task"]
        }
      }
      // ... 78 more tools
    ]
  },
  "id": 1
}

Task 2.3: Add SSE Endpoint for Events (if supported)

@Get('mcp/events')
@Sse()
async streamEvents(@Query('agentId') agentId: string): Observable<MessageEvent> {
  return this.eventService.getEventStream(agentId).pipe(
    map(event => ({
      data: JSON.stringify(event),
      type: event.type,
      id: event.id
    }))
  );
}

Phase 3: Agent Registration (Day 3)

Owner: Backend agent Deliverable: Cowork auto-registration on connect

Task 3.1: Add Connector Identification

When Claude Desktop connects, identify it as Cowork:

// In MCP HTTP controller
private identifyAgent(request: Request): AgentIdentity {
  const userAgent = request.headers['user-agent'];
  const clientInfo = request.headers['x-client-info'];

  // Claude Desktop likely sends identifying headers
  if (userAgent?.includes('Claude') || clientInfo?.includes('desktop')) {
    return {
      platform: 'cowork',
      agentType: 'browser',
      capabilities: {
        canBrowse: true,
        canTest: true,
        canResearch: true,
        canCode: false  // Cowork doesn't have direct file access
      }
    };
  }

  return { platform: 'unknown', agentType: 'generic' };
}

Task 3.2: Auto-Register on First Request

async handleInitialize(params: InitializeParams, id: number) {
  const agentId = `cowork-${params.clientInfo?.name || 'desktop'}-${Date.now()}`;

  // Register in agent registry
  await this.agentService.register({
    agentId,
    platform: 'cowork',
    workspace: params.workspace || 'editor2',
    capabilities: this.identifyAgent(params),
    connectedAt: new Date()
  });

  return {
    jsonrpc: '2.0',
    result: {
      protocolVersion: '2024-11-05',
      serverInfo: {
        name: 'gograb-ai',
        version: '4.0.0'
      },
      capabilities: {
        tools: {},
        resources: {},
        prompts: {}
      },
      // Include agent ID for future requests
      agentId
    },
    id
  };
}

Phase 4: Handoff Integration (Days 4-5)

Owner: Backend agent Deliverable: Cowork can receive and process handoffs

Task 4.1: Add check_handoffs Tool

Since push may not work, add a tool Cowork can call:

{
  name: 'check_handoffs',
  description: 'Check for pending handoffs assigned to this agent. Call periodically during idle time.',
  inputSchema: {
    type: 'object',
    properties: {
      agentId: { type: 'string', description: 'Your agent ID from initialization' }
    }
  },
  handler: async ({ agentId }) => {
    const pending = await this.handoffService.getPendingForAgent(agentId);
    const assigned = await this.handoffService.getAssignedToAgent(agentId);

    return {
      pendingCount: pending.length,
      assignedCount: assigned.length,
      handoffs: [...pending, ...assigned].map(h => ({
        handoffId: h.handoffId,
        summary: h.summary,
        priority: h.priority,
        fromAgent: h.fromAgent,
        createdAt: h.createdAt
      }))
    };
  }
}

Task 4.2: Add accept_handoff and complete_handoff Tools

Wrap existing REST endpoints as MCP tools:

{
  name: 'accept_handoff',
  description: 'Accept a handoff assigned to you',
  inputSchema: {
    type: 'object',
    properties: {
      handoffId: { type: 'string' },
      agentId: { type: 'string' }
    },
    required: ['handoffId', 'agentId']
  }
},
{
  name: 'complete_handoff',
  description: 'Mark a handoff as complete with results',
  inputSchema: {
    type: 'object',
    properties: {
      handoffId: { type: 'string' },
      agentId: { type: 'string' },
      response: { type: 'string' },
      artifacts: { type: 'array', items: { type: 'object' } }
    },
    required: ['handoffId', 'agentId', 'response']
  }
}

Phase 5: Testing & Documentation (Day 5)

Owner: QA agent or any available agent Deliverable: Working integration with docs

Task 5.1: End-to-End Test Scenarios

1. Tool Discovery: Claude Desktop lists all 79 tools
2. Tool Execution: Call preflight, log_decision, get_stats
3. Agent Registration: Cowork appears in agent list
4. Handoff Reception: Cursor creates handoff, Cowork receives via check_handoffs
5. Handoff Completion: Cowork completes handoff, Cursor receives notification

Task 5.2: Update Documentation

• Update COWORK-INTEGRATION-LIMITATIONS.md with resolution
• Add docs/english/AI/CLAUDE-DESKTOP-CONNECTOR-SETUP.md
• Update MCP reference with new tools

Risk Assessment

Success Criteria

Minimum Viable Integration (MVP)

• Claude Desktop discovers 79 tools via connector
• Tool calls execute successfully (preflight, log_decision)
• Cowork appears in agent registry
• Handoffs can be received via polling tool

Full Integration

• Real-time handoff notifications (if SSE works)
• Bidirectional handoffs (Cowork → Cursor)
• Session persistence across restarts
• Published as official extension

Dependencies

1. Backend-ai-api must be running - For any validation
2. Claude Desktop with Connectors feature - Beta access required
3. Phase 1 must complete before Phase 2 - Protocol determines implementation
4. Network access - Localhost for dev, HTTPS for prod

Handoff Instructions for Codebase Agents

For Cursor/Claude Code Agent

SESSION: 79
SUBSESSION: Start at 79.1

FIRST TASK:
1. Call `set_session` with sessionNumber=79
2. Start backend-ai-api: cd apis/backend-ai-api && npm run start:dev
3. Follow Phase 1 validation tasks
4. Document findings in 79.1-protocol-validation-results.md

DECISION TRACKING:
- Log all architectural decisions via log_decision
- Report outcomes for learning system

HANDOFF PROTOCOL:
- If blocked, create handoff to appropriate agent type
- Check for pending handoffs periodically

For Cowork Agent (Me)

MY LIMITATIONS:
- Cannot call MCP tools without running backend
- Cannot receive push notifications
- Must use HTTP REST API or browser automation

MY CAPABILITIES:
- Create comprehensive documentation
- Research and analysis
- Browser-based testing via Claude in Chrome
- Coordination and planning

WHEN BACKEND IS RUNNING:
- I can validate connector by adding to Claude Desktop settings
- I can test tool discovery and execution
- I can verify handoff flow

Session Documents

Notes for Future Reference

Why This Matters Beyond Cowork

The MCP-over-HTTP protocol we implement here becomes the foundation for:

1. External partner integrations - Third parties can connect their agents
2. Mobile app AI features - Mobile clients can call MCP tools
3. Web-based AI panel - Browser-based MCP without extensions
4. Future LLM integrations - Not locked to Anthropic

Data Capture Opportunity

Every tool call through the connector should log:

• Request timestamp
• Tool name and arguments
• Response success/failure
• Execution time
• Agent identity

This feeds the learning system and provides training data for future model development.

Session 79 - Claude Desktop Connector Integration Initiated by: Cowork Agent Ready for: Codebase Agent Implementation