COWORK INTEGRATION LIMITATIONS

Comprehensive guidelines for AI-assisted development within the Editor platform

Cowork Integration Limitations & Proposed Solutions

Last Updated: February 1, 2026 (Session 78)
Author: GoGrab Multi-Agent Team
Purpose: Documentation for Cowork agent to understand current limitations and integration possibilities

Executive Summary

We've built a comprehensive multi-agent infrastructure for real-time agent-to-agent communication, task handoffs, and collaborative development. The problem: Cowork (Claude Desktop) can only interact with our system through browser automation, which fundamentally limits its ability to participate as a first-class agent.

Current State:

Cowork sees our dashboard visually via Playwright/browser automation
Cowork cannot receive push notifications for new handoffs
Cowork cannot call our MCP tools natively
Communication is one-way: we can display to Cowork, but Cowork can't respond without human intervention

Desired State:

Cowork registers as an agent in our system
Cowork receives real-time handoff notifications
Cowork can call our 78 MCP tools directly
Bidirectional agent-to-agent communication

What We've Built

1. MCP Server with 78 Tools

Our Model Context Protocol server provides a comprehensive toolkit for AI agents:

Category	Tools	Description
Session Management	10	Session tracking, context, modes
Decision & Learning	16	Decision logging, pattern mining
Multi-Agent	12	Handoffs, messaging, RPC, discovery
Browser Automation	9	Web scraping, page interaction
Desktop Connectivity	7	File ops, commands, clipboard
Code Generation	8	Module scaffolding, templates, quality
Outcome Tracking	2	Success/failure reporting
Total	78

Key MCP Endpoints:

Base URL: https://ai-api.gograb.space/ai-api/mcp
POST /preflight         - Get context before task
POST /tools/call        - Execute any MCP tool
GET  /tools             - List available tools
GET  /openapi.yaml      - OpenAPI specification

2. Dual WebSocket Gateway

We support two transport protocols for maximum compatibility:

Socket.io Gateway (Port 3000)

Used by Angular dashboard, VSCode extension
Event-based with automatic reconnection
Namespace: /mcp

Native WebSocket Gateway (Path: /ws)

Used by Chrome Extension (MV3 service worker limitations)
Pure WebSocket for clients that can't use socket.io-client
Same event protocol, different transport

Connection Info:

Production: wss://ai-api.gograb.space/ws
Local:      ws://localhost:3000/ws

Query Params:
  ?agentId=your-agent-id
  &platform=cowork|cursor|claude-code|external
  &instanceId=unique-instance
  &workspace=editor2
  &token=your-auth-token

3. Chrome Extension with Agent Registration

Our Chrome extension demonstrates agent connectivity:

Registers as browser-agent with capabilities
Connects via Native WebSocket
Receives handoff notifications in real-time
Can execute browser-based tasks

4. VSCode Extension with Handoff Notifications

Registers as IDE agent
Shows handoff notifications via VSCode API
Can accept/decline handoffs
Routes tasks to appropriate agent

5. Multi-Agent Dashboard

Angular-based real-time dashboard showing:

Connected agents (online/offline status)
Pending handoffs with priority
Handoff history and analytics
Agent metrics

6. Handoff System with RPC

Handoff Types:

code-to-browser - Cursor/IDE needs browser testing
browser-to-code - Browser agent needs code changes
code-to-code - Agent-to-agent code collaboration

Handoff Lifecycle:

created → assigned → acknowledged → in_progress → completed/failed
              ↓
           declined → (reassigned or expired)

Current Cowork Integration Status

How Cowork Currently Interacts

Cowork uses Playwright browser automation to:

Navigate to our dashboard URL
Take screenshots to "see" the current state
Click buttons to interact
Read DOM content for information

What Works

Feature	Status	Notes
View dashboard	✅ Works	Via browser_navigate + browser_snapshot
See agent list	✅ Works	Visual reading of DOM
See pending handoffs	✅ Works	If dashboard is open
Manual refresh	✅ Works	Can click refresh buttons
Create handoffs (manual)	✅ Works	Can fill forms and submit

What Doesn't Work

Feature	Status	Issue
Push notifications	❌ Broken	WebSocket can't push to browser Cowork controls
Real-time updates	❌ Broken	Must manually refresh/snapshot
Direct messaging	❌ Broken	No WebSocket connection from Cowork
MCP tool calls	❌ Broken	Cowork can't natively call MCP
Agent registration	❌ Broken	Cowork isn't registered as an agent
Handoff acceptance	❌ Broken	Must simulate clicks vs. real acknowledgment

Technical Limitations Found

1. Cowork Controls the Browser, Not Our WebSocket

┌─────────────────────────────────────────────────────────────┐
│                     CURRENT STATE                           │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   Cowork (Claude Desktop)                                   │
│        │                                                    │
│        ▼                                                    │
│   Playwright Browser Instance                               │
│        │                                                    │
│        ▼ (HTTP only)                                        │
│   Our Dashboard (Angular)                                   │
│        │                                                    │
│        ▼ (WebSocket)                                        │
│   Backend AI API ← WebSocket → Cursor Agent                 │
│                                                             │
│   Problem: Cowork sees the dashboard, but it's the         │
│   DASHBOARD that has the WebSocket, not Cowork!            │
│                                                             │
└─────────────────────────────────────────────────────────────┘

When we push a handoff.created event:

Dashboard receives it ✅
Dashboard updates its UI ✅
Cowork doesn't know about it ❌ (must take another screenshot)

2. No MCP Integration with Cowork

Claude Desktop has its own MCP client, but:

It connects to local MCP servers via stdio
It does NOT support connecting to remote MCP servers via HTTP/WebSocket
Our MCP server is cloud-hosted at ai-api.gograb.space

Cowork can make HTTP requests, but this requires:

Explicit instructions each time
Manual API calls, not native MCP protocol
No automatic tool discovery

3. Browser Automation ≠ Real-time Agent Communication

Aspect	Browser Automation	Real Agent Integration
Connection	Polling (snapshot)	Push (WebSocket)
Latency	Seconds (human-like)	Milliseconds
State	Visual parsing	Structured data
Reliability	Flaky (DOM changes)	Stable (API contract)
Bandwidth	High (screenshots)	Low (JSON events)

4. The Polling vs Push Notification Gap

Current flow (polling):

1. Cursor creates handoff
2. Backend stores and broadcasts via WebSocket
3. Dashboard shows handoff
4. Cowork takes screenshot (maybe)
5. Cowork notices handoff (maybe)
6. Cowork takes action (delay: seconds to never)

Ideal flow (push):

1. Cursor creates handoff
2. Backend stores and broadcasts via WebSocket
3. Cowork receives handoff.created event
4. Cowork processes and responds immediately
5. Round-trip time: <500ms

The Ideal Integration

What We Want

┌─────────────────────────────────────────────────────────────┐
│                     IDEAL STATE                             │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   Cowork (Claude Desktop)                                   │
│        │                                                    │
│        ├──► WebSocket Connection ◄────────────────┐        │
│        │    to ai-api.gograb.space/ws              │        │
│        │                                           │        │
│        └──► MCP Client Connection                  │        │
│             (native tool calling)                  │        │
│                                                    │        │
│   Backend AI API ◄──────────────────────────────►│        │
│        │                                           │        │
│        ├── Cursor Agent (via MCP stdio)           │        │
│        ├── Chrome Extension (via Native WS)       │        │
│        ├── VSCode Extension (via Socket.io)       │        │
│        └── Cowork (via Native WS or MCP)    ◄────┘        │
│                                                             │
│   All agents can:                                           │
│   ✓ Receive push notifications                              │
│   ✓ Call MCP tools                                          │
│   ✓ Send/receive handoffs                                   │
│   ✓ Collaborate in real-time                                │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Cowork as a First-Class Agent

Agent Registration
- Cowork connects with agentId: "cowork-desktop-1"
- Platform: cowork
- Capabilities: { canBrowse: true, canTest: true }

Real-time Handoff Notifications

{
  "event": "handoff.created",
  "data": {
    "handoffId": "h-abc123",
    "fromAgent": "cursor-agent",
    "toAgentType": "browser",
    "type": "code-to-browser",
    "summary": "Test login flow after password reset fix",
    "priority": "high"
  }
}

MCP Tool Access
- Cowork can call preflight, log_decision, find_similar
- Cowork can call handoff.accept, handoff.complete
- All 78 tools available natively
Bidirectional Communication
- Cowork can create handoffs TO Cursor
- Cowork can respond to RPC requests
- No human in the loop for agent-to-agent tasks

Proposed Solutions

Option A: Cowork Uses Our MCP Server (Recommended)

How it would work:

Cowork connects to our WebSocket endpoint as an agent
Cowork makes HTTP calls to our MCP REST API
Combined: real-time events + MCP tools

Requirements from Cowork/Anthropic:

Ability to maintain a WebSocket connection during session
Ability to make HTTP calls to external MCP API

Connection example:

// WebSocket for real-time events
const ws = new WebSocket('wss://ai-api.gograb.space/ws?agentId=cowork-1&platform=cowork&workspace=editor2');

ws.onmessage = (event) => {
  const { event: eventType, data } = JSON.parse(event.data);
  if (eventType === 'handoff.created') {
    // Handle new handoff
  }
};

// MCP API for tool calls
const response = await fetch('https://ai-api.gograb.space/ai-api/mcp/tools/call', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-MCP-API-Key': 'mcp_xxx',
    'X-MCP-Project-Id': 'project-id'
  },
  body: JSON.stringify({
    name: 'preflight',
    arguments: { task: 'Test login flow' }
  })
});

Pros:

✅ Full integration with our system
✅ Real-time push notifications
✅ All 78 MCP tools available
✅ Agent-to-agent handoffs work

Cons:

❓ Requires Anthropic to support external connections
❓ May need WebSocket permission

Option B: Cowork Polls Our REST API

How it would work:

Cowork periodically calls GET /handoffs/pending?agentType=browser
Cowork processes new handoffs
Cowork calls POST /handoffs/{id}/accept to claim

API Endpoints:

GET  /ai-api/handoffs/pending?agentType=browser
POST /ai-api/handoffs/{id}/accept
POST /ai-api/handoffs/{id}/complete
POST /ai-api/handoffs/{id}/decline

Pros:

✅ Works with current HTTP capabilities
✅ No WebSocket required
✅ Simple to implement

Cons:

❌ Not real-time (polling delay)
❌ Wastes API calls when no handoffs
❌ Still not a "registered" agent

Option C: We Create a Cowork-Specific Connector

How it would work:

We build a "Cowork Bridge" that runs locally
Bridge connects to our WebSocket AND to Cowork via file/pipe
Bridge translates WebSocket events to Cowork-readable format

Architecture:

Our Backend ◄──WebSocket──► Cowork Bridge ◄──stdio/file──► Cowork

Implementation:

// cowork-bridge.js (runs locally)
const WebSocket = require('ws');
const fs = require('fs');

const ws = new WebSocket('wss://ai-api.gograb.space/ws?agentId=cowork-bridge&platform=cowork');

ws.on('message', (data) => {
  const event = JSON.parse(data);
  
  // Write to file that Cowork can read
  fs.writeFileSync('~/.cowork-events/latest.json', JSON.stringify(event));
  
  // Or use MCP stdio protocol
  console.log(JSON.stringify({
    jsonrpc: '2.0',
    method: 'notification',
    params: event
  }));
});

Pros:

✅ Works around Cowork limitations
✅ Real-time via local bridge
✅ Can be enhanced incrementally

Cons:

❌ Requires local process
❌ More complexity
❌ User must run bridge

Option D: Anthropic Exposes MCP Integration for Cowork

What we need Anthropic to do:

Allow Cowork to connect to remote MCP servers (not just stdio)
Allow Cowork to maintain WebSocket connections
Register Cowork as a proper MCP client

MCP Server Config (if supported):

{
  "mcpServers": {
    "gograb-ai": {
      "type": "http",
      "url": "https://ai-api.gograb.space/ai-api/mcp",
      "auth": {
        "type": "api-key",
        "header": "X-MCP-API-Key",
        "value": "${MCP_API_KEY}"
      }
    }
  }
}

Pros:

✅ Native integration
✅ Best user experience
✅ Anthropic maintains compatibility

Cons:

❓ Dependent on Anthropic roadmap
❓ May take time to implement
❓ Uncertain timeline

Our MCP Server Details

Connection Info

Environment	URL
Production	`https://ai-api.gograb.space/ai-api/mcp`
WebSocket	`wss://ai-api.gograb.space/ws`
Local Dev	`http://localhost:3000/ai-api/mcp`
Local WS	`ws://localhost:3000/ws`

Authentication

Option 1: API Key (recommended for external agents)

X-MCP-API-Key: mcp_your_api_key
X-MCP-Project-Id: your-project-id

Option 2: JWT Token

Authorization: Bearer your_jwt_token

Key Tools for Agent Communication

Tool	Purpose	Example
`preflight`	Get context before task	`{ task: "Test login flow" }`
`log_decision`	Record a decision	`{ type, question, chosen, reasoning }`
`handoff.create`	Create a handoff	`{ toAgentType, summary, tasks }`
`handoff.accept`	Accept assigned handoff	`{ handoffId }`
`handoff.complete`	Mark handoff done	`{ handoffId, response }`
`agent.list`	List connected agents	`{ workspace }`
`agent.message`	Direct message to agent	`{ toAgent, content }`

How to Register as an Agent

Via WebSocket:

const ws = new WebSocket('wss://ai-api.gograb.space/ws');

ws.onopen = () => {
  ws.send(JSON.stringify({
    event: 'agent.register',
    data: {
      agentId: 'cowork-desktop-1',
      platform: 'cowork',
      instanceId: 'unique-instance-id',
      workspace: 'editor2',
      capabilities: {
        canCode: false,
        canBrowse: true,
        canTest: true,
        canResearch: true
      }
    }
  }));
};

Via REST API:

curl -X POST https://ai-api.gograb.space/ai-api/agents/register \
  -H "Content-Type: application/json" \
  -H "X-MCP-API-Key: mcp_xxx" \
  -d '{
    "agentId": "cowork-desktop-1",
    "platform": "cowork",
    "workspace": "editor2",
    "capabilities": {
      "canBrowse": true,
      "canTest": true
    }
  }'

Request to Cowork Team/Agent

We'd like to understand Cowork's capabilities and limitations:

Questions

Can Cowork connect to external MCP servers?
- Not just local stdio servers, but HTTP/WebSocket MCP endpoints
- Can we register our MCP server in Cowork's configuration?
Can Cowork receive WebSocket push notifications?
- Maintain a persistent WebSocket connection during session
- React to events like handoff.created without polling
Is there a way for Cowork to register as an agent?
- Send a registration message on session start
- Maintain agent status (online/offline)
- Receive direct messages from other agents
Can Cowork make HTTP calls with custom headers?
- For API key authentication
- For structured API requests
What is Cowork's MCP client configuration format?
- Can we add remote servers to claude_desktop_config.json?
- What transport protocols are supported?

What We're Willing to Build

If Anthropic/Cowork can meet us halfway, we're ready to:

Build a Cowork-specific REST API endpoint
Create a polling-based integration if push isn't possible
Develop a local bridge/connector if needed
Provide detailed API documentation and SDKs

Architecture Diagrams

Current State (Browser Automation Only)

┌─────────────────────────────────────────────────────────────────────┐
│                        CURRENT ARCHITECTURE                         │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│                              ┌──────────────────┐                   │
│                              │   Cowork Agent   │                   │
│                              │  (Claude Desktop)│                   │
│                              └────────┬─────────┘                   │
│                                       │                             │
│                                       │ Browser Automation          │
│                                       │ (Playwright)                │
│                                       ▼                             │
│  ┌─────────────┐              ┌──────────────────┐                  │
│  │   Cursor    │◄──Socket.io──│  Angular         │                  │
│  │   Agent     │              │  Dashboard       │                  │
│  └──────┬──────┘              └────────┬─────────┘                  │
│         │                              │                            │
│         │ MCP/stdio                    │ Socket.io                  │
│         ▼                              ▼                            │
│  ┌─────────────────────────────────────────────────┐                │
│  │              Backend AI API                      │                │
│  │  ┌───────────────┐    ┌────────────────────┐    │                │
│  │  │ Socket.io GW  │    │ Native WS Gateway  │    │                │
│  │  │ (/:3000/mcp)  │    │ (/:3000/ws)        │    │                │
│  │  └───────────────┘    └────────────────────┘    │                │
│  │              │                 │                │                │
│  │              ▼                 ▼                │                │
│  │       ┌────────────────────────────┐            │                │
│  │       │   AgentService / Handoffs  │            │                │
│  │       │   MongoDB Persistence      │            │                │
│  │       └────────────────────────────┘            │                │
│  └─────────────────────────────────────────────────┘                │
│                                                                     │
│  ⚠️  Cowork can SEE the dashboard but cannot RECEIVE push events   │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Ideal State (Direct Agent Integration)

┌─────────────────────────────────────────────────────────────────────┐
│                        IDEAL ARCHITECTURE                           │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌─────────────┐   ┌─────────────┐   ┌──────────────────┐           │
│  │   Cursor    │   │   Chrome    │   │   Cowork Agent   │           │
│  │   Agent     │   │   Ext       │   │  (Claude Desktop)│           │
│  └──────┬──────┘   └──────┬──────┘   └────────┬─────────┘           │
│         │                 │                   │                     │
│         │ MCP/stdio       │ Native WS         │ WebSocket + MCP     │
│         │                 │                   │ (IDEAL!)            │
│         ▼                 ▼                   ▼                     │
│  ┌─────────────────────────────────────────────────────┐            │
│  │              Backend AI API                          │            │
│  │  ┌───────────────┐    ┌────────────────────┐        │            │
│  │  │ Socket.io GW  │    │ Native WS Gateway  │        │            │
│  │  └───────┬───────┘    └─────────┬──────────┘        │            │
│  │          │                      │                   │            │
│  │          ▼                      ▼                   │            │
│  │    ┌─────────────────────────────────────┐          │            │
│  │    │      Unified Agent Service          │          │            │
│  │    │  • Agent Registration               │          │            │
│  │    │  • Handoff Routing                  │          │            │
│  │    │  • RPC Dispatch                     │          │            │
│  │    │  • Push Notifications               │          │            │
│  │    └─────────────────────────────────────┘          │            │
│  └─────────────────────────────────────────────────────┘            │
│                                                                     │
│  ✅ All agents connected directly                                   │
│  ✅ Real-time push notifications                                    │
│  ✅ Agent-to-agent handoffs                                         │
│  ✅ MCP tool access for all                                         │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Handoff Flow (Code-to-Browser)

┌──────────────────────────────────────────────────────────────────────┐
│                    HANDOFF FLOW: Code-to-Browser                     │
├──────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  1. Cursor implements feature                                        │
│                   │                                                  │
│                   ▼                                                  │
│  2. Cursor creates handoff                                           │
│     { type: "code-to-browser", toAgentType: "browser" }              │
│                   │                                                  │
│                   ▼                                                  │
│  3. Backend routes to best browser agent                             │
│     (Cowork, Chrome Extension, etc.)                                 │
│                   │                                                  │
│                   ├─────────────────────────────────────┐            │
│                   │                                     │            │
│                   ▼                                     ▼            │
│  4a. Push event to Cowork (IDEAL)     4b. Poll API (FALLBACK)        │
│      { event: "handoff.assigned" }        GET /handoffs/pending      │
│                   │                                     │            │
│                   ▼                                     ▼            │
│  5. Browser agent accepts                                            │
│     POST /handoffs/{id}/accept                                       │
│                   │                                                  │
│                   ▼                                                  │
│  6. Browser agent executes tasks                                     │
│     • Navigate to app                                                │
│     • Test the feature                                               │
│     • Take screenshots                                               │
│                   │                                                  │
│                   ▼                                                  │
│  7. Browser agent completes handoff                                  │
│     POST /handoffs/{id}/complete                                     │
│     { response: { screenshots, testResults, notes } }                │
│                   │                                                  │
│                   ▼                                                  │
│  8. Cursor receives completion event                                 │
│     { event: "handoff.completed" }                                   │
│                                                                      │
└──────────────────────────────────────────────────────────────────────┘

Next Steps

Immediate: Cowork confirms which of Options A-D is feasible
Short-term: Implement the chosen integration approach
Medium-term: Test end-to-end handoff flow
Long-term: Full multi-agent collaboration

Cowork Integration Limitations & Proposed Solutions

Executive Summary

What We've Built

1. MCP Server with 78 Tools

2. Dual WebSocket Gateway

Socket.io Gateway (Port 3000)

Native WebSocket Gateway (Path: /ws)

3. Chrome Extension with Agent Registration

4. VSCode Extension with Handoff Notifications

5. Multi-Agent Dashboard

6. Handoff System with RPC

Current Cowork Integration Status

How Cowork Currently Interacts

What Works

What Doesn't Work

Technical Limitations Found

1. Cowork Controls the Browser, Not Our WebSocket

2. No MCP Integration with Cowork

3. Browser Automation ≠ Real-time Agent Communication

4. The Polling vs Push Notification Gap

The Ideal Integration

What We Want

Cowork as a First-Class Agent

Proposed Solutions

Option A: Cowork Uses Our MCP Server (Recommended)

Option B: Cowork Polls Our REST API

Option C: We Create a Cowork-Specific Connector

Option D: Anthropic Exposes MCP Integration for Cowork

Our MCP Server Details

Connection Info

Authentication

Key Tools for Agent Communication

How to Register as an Agent

Request to Cowork Team/Agent

Questions

What We're Willing to Build

Architecture Diagrams

Current State (Browser Automation Only)

Ideal State (Direct Agent Integration)

Handoff Flow (Code-to-Browser)

Next Steps

Related Documentation