Merge 1f2095d030 into 9e145d9ceb

README.md

@@ -68,7 +68,7 @@ Unattended runs never self-approve: their asks park in an inbox until a human an
 
 - **Produce real deliverables** - documents, spreadsheets, reports, and web pages land as files you can open and share.
 - **Work from Slack** - mention `@OpenWorker` in a channel; a session opens on your desktop, the work happens with your tools, and the answer comes back as a thread reply.
-- **Use your everyday tools** - 25+ integrations including GitHub, Slack, Jira, Notion, Linear, HubSpot, Outlook, monday.com, Gmail, and Google Calendar, plus your **terminal and local files**. Any tool reachable over [MCP](https://modelcontextprotocol.io/) plugs in too, with per-tool control.
+- **Use your everyday tools** - 25+ integrations including GitHub, Slack, Jira, Notion, Linear, HubSpot, Outlook, monday.com, Gmail, and Google Calendar, plus your **terminal and local files**. Any tool reachable over [MCP](https://modelcontextprotocol.io/) (see [MCP Setup Guide](docs/mcp-setup.md)) plugs in too, with per-tool control.
 - **Run on a schedule** - automations for recurring work: a morning brief, a weekly report, a standing watch over a channel. Runs land in the app with full transcripts.
 - **Ask before acting** - writes, sends, and shell commands are approval-gated, with an optional auto-approve mode that still escalates anything uncertain - see [Governed by design](#governed-by-design).
 

docs/mcp-setup.md

@@ -0,0 +1,50 @@
+# Adding MCP Servers to OpenWorker
+
+OpenWorker supports integrating with Model Context Protocol (MCP) servers via configuration files. This allows you to extend the agent's capabilities with tools from any standard-compliant MCP server.
+
+## Configuration Files
+OpenWorker looks for `mcp.json` in two locations:
+1.  **Workspace Specific:** `<workspace>/.coworker/mcp.json` (overrides global settings).
+2.  **Global:** `~/.config/coworker/mcp.json`
+
+## Configuration Format
+The configuration follows the standard MCP configuration format:
+
+```json
+{
+  "mcpServers": {
+    "server-name": {
+      "command": "node",
+      "args": ["/path/to/server/index.js"],
+      "env": {
+        "API_KEY": "your_key"
+      }
+    }
+  }
+}
+```
+
+## Key Features
+- **Auto-detection:** The system automatically identifies the transport layer (`stdio` or `HTTP` / `SSE`) based on your configuration.
+- **Variable Expansion:** Use `${VAR}` syntax in `command`, `args`, `env`, `url`, and `headers`. These are resolved at load time using the system's environment and `.env` files.
+- **Tool Filtering:** Optionally restrict which tools from an MCP server are exposed to the agent:
+  - `include_tools`: Explicit list of allowed tool names.
+  - `exclude_tools`: List of blocked tool names.
+
+## Quick Start Example
+To add a local server, create `.coworker/mcp.json` in your project root:
+```json
+{
+  "mcpServers": {
+    "my-tool": {
+      "command": "python",
+      "args": ["/path/to/server.py"],
+      "env": {
+        "DEBUG": "true"
+      }
+    }
+  }
+}
+```
+
+The agent will recognize these tools immediately on the next run.