Handoff: Cowork → Codebase Agent

Created: February 1, 2026 From: Cowork Agent (Claude Desktop - Session 78→79) To: Codebase Agent (Cursor/Claude Code) Priority: HIGH Type: implementation

TL;DR

Claude Desktop now has Custom Connectors (Beta) that support remote MCP server URLs. Your job: validate the protocol, implement necessary backend changes, and make Cowork a first-class agent.

Context You Need

What Happened in Session 78

• Fixed Chrome extension authentication sync
• Enhanced gograb-ai panel with tabs (Chat, Agents, Handoffs, Mind)
• Fixed handoff routing to use capabilities instead of platform
• Documented Cowork limitations in docs/english/AI/COWORK-INTEGRATION-LIMITATIONS.md

What I (Cowork) Discovered Today

1. Claude Desktop Settings → Connectors → "Add custom connector" (Beta)
2. Has "Remote MCP server URL" field
3. Has "Advanced settings" (likely for auth)
4. This is the integration path we've been waiting for

What I Cannot Do (Cowork Limitations)

• Cannot set session via MCP (backend not running when I tried)
• Cannot receive push notifications
• Cannot test connector myself (need you to run backend first)

Your Mission

Phase 1: Validate Protocol (CRITICAL - DO FIRST)

You need to figure out what protocol Claude Desktop expects.

Steps:

1. Set session: set_session({ sessionNumber: 79, workspace: 'editor2' })
2. Start backend: cd apis/backend-ai-api && npm run start:dev
3. Add custom connector in Claude Desktop:
   • Name: "GoGrab AI Test"
   • URL: http://localhost:3001/ai-api/mcp
4. Observe what happens:
   • Does it discover tools?
   • What HTTP requests does it make? (Check network tab)
   • What errors appear?

Document findings in: session-79/79.1-protocol-validation-results.md

Phase 2: Implement Based on Findings

If current endpoint works → Great, move to Phase 3

If protocol mismatch → Implement MCP JSON-RPC endpoint:

// apis/backend-ai-api/src/app/mcp-gateway/mcp-http.controller.ts
@Post('mcp')
async handleMcpRequest(@Body() request: McpJsonRpcRequest) {
  // Handle: initialize, tools/list, tools/call, resources/list, prompts/list
}

See full implementation spec in session-79/README.md

Phase 3: Agent Registration

Make Cowork auto-register when it connects:

• Identify by User-Agent or client info headers
• Create agent registry entry
• Return agentId in initialize response

Phase 4: Handoff Tools

Add tools for Cowork to check/accept/complete handoffs:

• check_handoffs - Poll for pending handoffs
• accept_handoff - Claim a handoff
• complete_handoff - Submit results

Phase 5: Test & Document

End-to-end validation that:

1. Tools are discoverable
2. Tools execute correctly
3. Agent registration works
4. Handoffs flow between agents

Files to Modify/Create

Definitely Modify

• apis/backend-ai-api/src/app/mcp-gateway/mcp-gateway.module.ts - Add new controller
• apis/backend-ai-api/src/app/mcp-gateway/ - Add mcp-http.controller.ts if needed
• MCP/mcp-gograb-ai/src/server.ts - Add handoff tools (check, accept, complete)

Definitely Create

• docs/english/sessions/editor2/session-79/79.1-protocol-validation-results.md
• docs/english/AI/CLAUDE-DESKTOP-CONNECTOR-SETUP.md (when working)

Potentially Modify (based on Phase 1 findings)

• apis/backend-ai-api/src/app/infrastructure/services/agent.service.ts
• apis/backend-ai-api/src/app/infrastructure/services/handoff.service.ts

Decision Logging Reminders

Log decisions for:

1. Protocol choice (JSON-RPC vs REST vs other)
2. Authentication method
3. Event delivery mechanism (SSE vs polling vs none)
4. Tool additions to MCP

Use: log_decision({ type: 'architecture', question: '...', chosen: '...', reasoning: '...' })

Success Criteria Checklist

• Phase 1 complete: Protocol documented
• Phase 2 complete: Backend compatible with connector
• Phase 3 complete: Cowork auto-registers as agent
• Phase 4 complete: Handoff tools work
• Phase 5 complete: E2E tests pass

Risks to Watch

1. Beta feature may have bugs - Document workarounds
2. Auth may not be configurable - Test localhost first
3. No push notification support - check_handoffs polling is the fallback
4. Rate limiting - Don't hammer the connector

Communication Protocol

If You Get Stuck

Create handoff back to me (Cowork) with:

• What you tried
• What failed
• What you need

If You Complete Successfully

Create summary document with:

• Working configuration
• Any gotchas discovered
• Recommended next steps

Sub-Session Numbering

• 79.1 - Protocol Validation
• 79.2 - MCP HTTP Gateway (if needed)
• 79.3 - Agent Registration
• 79.4 - Handoff Integration
• 79.5 - Testing & Documentation

Increment sub-session when switching major tasks.

Why This Matters

This isn't just about Cowork integration. The protocol we implement becomes:

• External partner integration standard
• Mobile app AI access
• Web-based MCP access
• Foundation for platform autonomy

Every decision here shapes our medium-term goal of platform independence.

Handoff created by Cowork Agent Session 79 - Claude Desktop Connector Integration