Model Context Protocol (MCP)
Relevant source files
The following files were used as context for generating this wiki page:
The Model Context Protocol (MCP) in OpenWork is a standardized architecture used to connect AI agents to external tools, data sources, and services. It enables agents to move beyond simple text generation by providing them with a secure, extensible way to interact with local commands or remote HTTP endpoints. OpenWork acts as an MCP host, managing the lifecycle, configuration, and authorization of various MCP servers.
Sources: AGENTS.md, ee/apps/landing/public/llms.txt
Architecture and Configuration
The MCP implementation follows a client-server model where the OpenWork application (or the OpenWork server) acts as the host client that consumes tools provided by MCP servers. Configurations are stored within opencode.jsonc at either the project level or a global user-level configuration directory.
Configuration Schema
MCP servers are defined in the mcp block of the configuration file. Each entry consists of a unique server name and its corresponding configuration object.
The configuration identifies whether a server is local (run via a shell command) or remote (accessed via a URL).
Sources: apps/app/src/app/mcp.ts:1-10, apps/app/src/react-app/domains/connections/store.ts:440-460
Connection Types
OpenWork supports two primary methods for integrating MCP servers:
| Type | Description | Key Configuration Fields |
|---|---|---|
| Local | Executed as a child process on the host machine. | command (array), env (object) |
| Remote | Accessed over HTTP/HTTPS. | url (string), headers (object), oauth (object) |
Sources: apps/server/src/mcp.ts:12-25, apps/app/src/react-app/domains/connections/store.ts:445-465
Data Flow for Connecting an MCP
The connection process involves validating the server name, updating the local configuration file, and signaling the OpenCode engine to reload so it can discover the new tools.
Lifecycle Management
MCP servers transition through several states managed by the ConnectionsStore. These states are surfaced in the UI to provide feedback on the availability of tools.
| Status | Meaning |
|---|---|
connected | The server is active and tools are available. |
needs_auth | OAuth authorization is required before use. |
disabled | The server is present in config but explicitly deactivated. |
failed | The server failed to start or respond. |
disconnected | The server is offline or unreachable. |
Sources: apps/app/src/react-app/domains/session/surface/composer/composer.tsx:150-165, apps/app/src/react-app/domains/connections/store.ts:40-50
Server-Side API Endpoints
The openwork-server provides a REST API for managing MCP configurations programmatically. This is used by the desktop app and remote clients to synchronize workspace settings.
| Method | Endpoint | Description |
|---|---|---|
GET | /workspace/:id/mcp | Lists all configured MCP servers for a workspace. |
POST | /workspace/:id/mcp | Adds a new MCP server configuration. |
POST | /workspace/:id/mcp/:name/enabled | Toggles the enabled state of a specific MCP. |
DELETE | /workspace/:id/mcp/:name | Removes an MCP server from the configuration. |
DELETE | /workspace/:id/mcp/:name/auth | Removes stored OAuth credentials for a server. |
Sources: apps/server/src/server.ts:1520-1600
OAuth and Authorization
For remote MCP servers that require access to user-specific data (e.g., Notion, Google Drive), OpenWork implements an OAuth 2.0 flow.
The logoutMcpAuth function handles the removal of these credentials from the local credential store, typically located at ~/.config/opencode/mcp-auth.json.
Sources: apps/app/src/react-app/domains/connections/store.ts:545-580, apps/server/src/server.ts:1590-1620
WebMCP Provider
OpenWork also supports a "WebMCP" variant where web applications can provide context and tools directly to a model-aware browser or navigator. The WebMcpProvider component utilizes the navigator.modelContext API to expose tools like navigate_to or get_pricing_summary to the agent.
const result = modelContext.provideContext({ tools });
Sources: ee/apps/landing/components/webmcp-provider.tsx:145-155
Conclusion
The MCP implementation provides the critical bridge between the LLM and the user's operational environment. By managing these connections through a structured configuration and providing robust state management, OpenWork ensures that agents remain useful and extensible while maintaining security boundaries through explicit authorization and approval flows.
Sources: apps/app/src/react-app/domains/connections/store.ts:610-630, apps/server/src/server.ts:110-130