WorkBuddy External MCP Integration & Troubleshooting Guide

Why Connect MCP to WorkBuddy?

While WorkBuddy comes with built-in code analysis, file editing, and terminal execution, Model Context Protocol (MCP) bridges the gap when you need direct connectivity to external systems — such as local SQLite databases, remote GitHub repositories, or automated Chromium browser instances.

flowchart LR
    User[User Prompt / Task] --> WB[WorkBuddy Desktop / Agent]
    subgraph MCPClient[MCP Client Layer]
        WB --> Runtime[WorkBuddy MCP Runtime]
    end
    subgraph MCPServers[External MCP Capabilities]
        Runtime -->|STDIO / HTTP| S1[SQLite Server]
        Runtime -->|API Auth| S2[GitHub Server]
        Runtime -->|DevTools Protocol| S3[Playwright Browser]
    end

---

Production Configuration: mcp.json Template

WorkBuddy searches for mcp.json in your project root or global config directory (Note: the filename must be mcp.json, not .mcp.json).

Here is a tested, production-ready configuration snippet:

{
  "mcpServers": {
    "sqlite": {
      "command": "uvx",
      "args": ["mcp-server-sqlite", "--db-path", "./data/database.sqlite"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    },
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
    }
  }
}

---

Four-Step Onboarding Process

Step	Action	Key Verification
1. Runtime Setup	Ensure uv (Python) or node/npx (Node.js) is installed	Run uvx --version or npx -v in terminal
2. Config Placement	Place mcp.json in workspace root	Validate JSON syntax; no trailing commas
3. Authorization	Open the Connectors / Extensions panel in WorkBuddy	Click “Trust / Enable” explicitly to start processes
4. Live Verification	Ask WorkBuddy to list active tools	Prompt: Please list all available MCP tools

---

4 Common Connection Errors & Fixes

1. Stuck in “Not connected”

• Root Cause: The server configuration was saved, but you haven’t clicked “Trust” in the UI. For security reasons, WorkBuddy does not execute third-party binaries silently.
• Fix: Find the server entry in the Connectors tab and enable trust.

2. Sandbox Network Restrictions

• Root Cause: APIs hosted overseas may encounter network timeouts within constrained container environments.
• Fix: Provide a stable local proxy and expose HTTP_PROXY and HTTPS_PROXY in the server env object.

3. Hanging on NPX Prompts

• Fix: Always pass -y to commands (e.g. npx -y @modelcontextprotocol/...) to prevent waiting on interactive terminal prompts.

4. Browser Automation Alternative

• Pro Tip: In high-throughput workflows, native local Playwright scripts driven by WorkBuddy directly often outperform MCP wrapper servers in stability and execution speed.