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 serves as a standardized bridge to connect external services (such as Notion, Linear, and Stripe) with Large Language Models (LLMs) using the user's own credentials. It allows the LLM to access specific toolsets and data sources securely. In the current implementation, MCP is in an Alpha state while OAuth hardening and integration with the OpenCode engine are finalized.
MCP servers are treated as a primary extensibility system within the project, mapping directly to OpenCode primitives. These servers are configured via opencode.json files located within the project workspace or global configuration directories.
Sources: packages/app/src/app/pages/mcp.tsx:132-135, ARCHITECTURE.md:16-19, packages/app/src/app/app.tsx:2198-2200
Architecture and Integration
OpenWork integrates MCP through the OpenCode engine. The protocol supports both local and remote server types. Local servers typically run via CLI commands (e.g., using npx), while remote servers are accessed via HTTPS URLs.
Server Types
- Remote Servers: Connect via a URL and often utilize OAuth for authentication (e.g., Notion, HubSpot).
- Local Servers: Run as local processes triggered by specific commands (e.g., Chrome DevTools MCP).
Sources: packages/app/src/app/pages/mcp.tsx:189-200, packages/app/src/app/constants.ts:46-53
Connection Flow
The following diagram illustrates the lifecycle of adding and activating an MCP server within the OpenWork environment:
The system requires an engine reload after configuration changes to discover and activate the new toolsets provided by the MCP server.
Sources: packages/app/src/app/app.tsx:2327-2435, packages/app/src/app/pages/mcp.tsx:156-170
Configuration Management
MCP settings are persisted in opencode.json. OpenWork provides a UI to manage these configurations at two scopes:
- Project Scope:
.opencode/opencode.jsonoropencode.jsonwithin the active workspace. - Global Scope: User-level configuration for cross-project availability.
Sources: packages/app/src/app/pages/mcp.tsx:254-282, packages/app/src/app/app.tsx:2270-2275
Quick Connect Directory
OpenWork includes pre-configured "Quick Connect" options for popular services:
| Service | Description | Type | Auth |
|---|---|---|---|
| Notion | Pages, databases, and project docs. | Remote | OAuth |
| Linear | Sprints and ticket management. | Remote | OAuth |
| Sentry | Release tracking and error resolution. | Remote | OAuth |
| Stripe | Payments and subscriptions. | Remote | OAuth |
| Chrome DevTools | Browser automation. | Local | None |
Sources: packages/app/src/app/constants.ts:55-103
Authentication Flow (OAuth)
For remote servers requiring authentication, OpenWork launches an OAuth flow. This is managed by the McpAuthModal component and the OpenCode SDK.
A known issue in the Alpha stage involves a "double-restart" requirement where the engine must sometimes be reloaded twice: once to detect the configuration and a second time to activate the connection with valid tokens.
Sources: packages/app/src/app/components/mcp-auth-modal.tsx:1-12, packages/app/pr/notion-connection-fix.md:7-15, ARCHITECTURE.md:124-129
Server Status and Capabilities
OpenWork tracks the health and status of each MCP server. Statuses are derived from the mcp.status SDK endpoint.
Status Definitions
- Connected: Server is active and tools are available.
- Needs Auth: Requires OAuth completion.
- Register Client: Requires client registration before OAuth.
- Disabled: Configured but explicitly turned off in
opencode.json. - Failed: Connection error (often surfaced with specific error messages).
Sources: packages/app/src/app/pages/mcp.tsx:41-55, packages/app/src/app/app.tsx:2307-2315
Capabilities Summary
The UI displays specific capabilities for selected servers:
- Tools Enabled: The list of functional tools provided to the LLM.
- OAuth Ready: Indicates if the authentication path is configured.
- Usage Hint: Guidance on using the MCP server name in prompts to target specific tools.
Sources: packages/app/src/app/pages/mcp.tsx:358-380
Implementation Details
Configuration Structure
MCP servers are defined as key-value pairs within the mcp object of the configuration file.
{
"mcp": {
"notion": {
"type": "remote",
"url": "https://mcp.notion.com/mcp",
"enabled": true,
"oauth": {}
},
"chrome": {
"type": "local",
"command": ["npx", "-y", "chrome-devtools-mcp@latest"],
"enabled": true
}
}
}
Sources: packages/app/src/app/app.tsx:2356-2384, packages/app/src/app/constants.ts:98-103
Technical Requirements
- Host Mode: MCP management is strictly available in Host mode where the OpenCode engine is running locally or on a reachable machine.
- Tauri Runtime: File-based operations (like "Reveal in Finder") require the Tauri desktop shell.
- Workspace: A project folder must be active to read or write project-specific MCP settings.
Sources: packages/app/src/app/pages/mcp.tsx:120-128, packages/app/src/app/app.tsx:2276-2285
Summary
The Model Context Protocol (MCP) provides a vital extensibility layer for OpenWork, enabling the integration of third-party services as AI tools. By leveraging opencode.json for configuration and utilizing the OpenCode SDK for runtime management, the system maintains parity with OpenCode primitives while providing a high-level UI for complex OAuth and connection management. Continuous hardening of the OAuth flow and engine reload logic remains a priority for the protocol's transition out of the Alpha phase.