MCP (Model Context Protocol) VS Code Copilot Integration Guide

Configuration Requirements

System Prerequisites

• VS Code 1.102+ with GitHub Copilot extension (verify activation, not just installation)
• PiecesOS running locally - crashes on first launch are expected
• Active GitHub Copilot subscription - check billing page as GitHub silently fails payments
• System permissions - macOS screen recording access required (resets after OS updates)

Critical Ports and Endpoints

• Primary endpoint: http://localhost:39300/model_context_protocol/2024-11-05/sse
• Port variation: May randomly switch to 39301 after updates
• Verification command: netstat -an | grep 39300

Resource Requirements

Performance Impact

• PiecesOS RAM usage: 4-6GB during operation
• CPU impact: Constant OCR processing causes thermal issues
• LTM database growth: Grows indefinitely, queries timeout after 6 months
• Tool limit: Copilot fails around 128 tools

Time Investment

• Initial setup: 4-8 hours (not the advertised 30 minutes)
• Debugging sessions: Budget full afternoons
• Enterprise deployment: 2-3 full-time engineers required for maintenance

Critical Failure Modes

Common Connection Errors

• ECONNREFUSED localhost:39300 - Port changed or PiecesOS crashed
• Server did not respond to initialization - MCP server not properly started
• Tool invocation failed: timeout - PiecesOS memory/performance issues

Platform-Specific Issues

• macOS Sonoma 14.6.1: Screen recording permissions reset after updates
• Windows: McAfee quarantines PiecesOS as malware
• Corporate networks: Firewalls block localhost connections

Breaking Update Scenarios

• VS Code updates break MCP connections
• PiecesOS updates change API endpoints
• Copilot updates modify tool invocation protocols

Implementation Steps

Step 1: PiecesOS Setup

1. Install PiecesOS and grant all permissions immediately
2. Verify process running: ps aux | grep pieces (macOS/Linux)
3. Enable Long-Term Memory (15-20 minutes, may fail silently)
4. Locate actual port in logs: %APPDATA%\com.pieces.os\logs (Windows)

Step 2: VS Code Configuration

// .vscode/mcp.json
{
  "servers": {
    "pieces": {
      "type": "sse",
      "url": "http://localhost:39300/model_context_protocol/2024-11-05/sse",
      "debug": true
    }
  }
}

Step 3: Copilot Agent Mode

1. Open Copilot Chat: Cmd+Ctrl+I (macOS) or Ctrl+Alt+I (Windows)
2. Switch dropdown from "Ask" to "Agent"
3. Verify Pieces tools appear in Tools dropdown
4. Test with context queries

Debugging Procedures

Nuclear Reset Sequence (When Everything Fails)

1. Quit PiecesOS completely
2. Delete ~/.pieces directory (destroys all stored context)
3. Uninstall and reinstall PiecesOS
4. Remove all MCP config from VS Code
5. Restart in order: PiecesOS → VS Code → system

Log Locations

• VS Code MCP logs: View → Output → Model Context Protocol
• PiecesOS logs: Check application data directory
• Connection verification: Chrome DevTools for SSE debugging

Enterprise Deployment Considerations

Corporate IT Challenges

• Firewall restrictions: Localhost ports blocked by default
• Security software: Antivirus quarantines PiecesOS
• Group policies: Prevent network connections and screen recording
• Configuration deployment: Group policy MCP configs often fail

Performance at Scale

• Shared server mode: Not properly supported, causes database conflicts
• Team knowledge sharing: Rate limits and search quality issues
• Database cleanup: No automated cleanup tools available

Alternative Approaches Comparison

Approach	Setup Time	Resource Usage	Context Persistence	Maintenance
MCP Setup	4-8 hours	4-6GB RAM, high CPU	Works when stable	High - constant debugging
Extension-Only	5-15 minutes	50-100MB RAM	Session-only	Low - Microsoft maintained
API Direct	2-3 weeks	Variable	Full control	None - self-built
Workspace Context	Zero setup	50-200MB RAM	Session + Git history	Minimal

Success Indicators

• Pieces tools visible in Copilot Agent mode dropdown
• Context queries return relevant historical information
• No ECONNREFUSED errors in MCP logs
• PiecesOS process stable for >24 hours

Critical Warnings

• Production reliability: Expect regular failures requiring manual intervention
• Resource consumption: Unsuitable for resource-constrained environments
• Update fragility: Each component update introduces new failure modes
• Enterprise complexity: Requires dedicated maintenance team
• Context pollution: Shared databases degrade relevance over time

Recommended Resources

• MCP Specification - Essential for debugging
• VS Code MCP Documentation - Troubleshooting section
• Pieces MCP Setup - Configuration examples
• MCP Community Discussions - Real error solutions