MCP Server Management
Relevant source files
The following files were used as context for generating this wiki page:
MCP (Model Context Protocol) Server Management in Opcode provides a centralized interface for configuring, importing, and monitoring external tools and data sources that Claude Code can utilize. The system bridges the gap between the GUI and the underlying claude mcp CLI commands, allowing users to manage complex server configurations without manual terminal interactions.
Sources: src/components/MCPManager.tsx:21-25, src-tauri/src/commands/mcp.rs:1-10, README.md:95-101
System Architecture
The MCP management system follows a tiered architecture where the React frontend communicates via a TypeScript API wrapper to Rust-based Tauri commands. These Rust commands ultimately wrap and execute the claude binary to persist and retrieve configurations.
The architecture ensures that Opcode remains synchronized with the standard Claude environment while providing an enhanced management interface.
Sources: src-tauri/src/commands/mcp.rs:81-88, src/lib/api.ts:1174-1180, web_server.design.md:32-40
Data Models
MCPServer Configuration
The core data structure represents an MCP server, supporting both standard input/output (stdio) and Server-Sent Events (SSE) transports.
| Field | Type | Description |
|---|---|---|
name | String | Unique identifier for the server. |
transport | String | Transport type: "stdio" or "sse". |
command | Option | The executable command (for stdio). |
args | Vec | Command arguments. |
env | HashMap<String, String> | Environment variables for the server process. |
url | Option | The endpoint URL (for SSE). |
scope | String | Configuration scope: "local", "project", or "user". |
Sources: src-tauri/src/commands/mcp.rs:24-42, src/lib/api.ts:314-332
Configuration Scopes
MCP servers are persisted in different scopes, determining their availability across projects.
- Local: Project-specific configuration.
- Project: Shared via
.mcp.jsonin the project root. - User: Global configuration available across all projects.
Sources: src-tauri/src/commands/mcp.rs:37-40, src/i18n/locales/en.json:445-449
Server Lifecycle Operations
Listing and Discovery
The system retrieves active and configured servers by parsing the output of claude mcp list. The Rust backend handles multi-line command output and parses it into structured MCPServer objects.
Creation and Modification
Adding a server involves passing transport-specific parameters (command/args for stdio, URL for SSE) to the mcp_add command.
#[tauri::command]
pub async fn mcp_add(
app: AppHandle,
name: String,
transport: String,
command: Option<String>,
args: Vec<String>,
env: HashMap<String, String>,
url: Option<String>,
scope: String,
) -> Result<AddServerResult, String>
Sources: src-tauri/src/commands/mcp.rs:92-103
Integration and Import/Export
Claude Desktop Integration
The MCPImportExport component allows users to synchronize their Claude Desktop settings. The backend locates the claude_desktop_config.json (on macOS or Linux/WSL), reads the mcpServers object, and converts them into Opcode-managed JSON configurations.
Serving Claude Code as MCP
Opcode can flip the relationship, running Claude Code itself as an MCP server for other applications. This is handled by the mcp_serve command, which spawns a detached process.
- Process Management: The PID is tracked in a
ProcessRegistryState. - Detachment: The child process is intentionally "forgotten" using
std::mem::forget(child)to allow it to outlive the GUI. - Atomic Registration: Registration fails if an instance is already running to prevent port conflicts.
Sources: src-tauri/src/commands/mcp.rs:480-510, src/components/MCPImportExport.tsx:156-165
UI Components and Interaction
MCPManager View
The primary interface uses a tabbed layout to separate server monitoring from configuration tasks.
| Tab | Component | Functionality |
|---|---|---|
| Servers | MCPServerList | Displays active servers and their connection status. |
| Add Server | MCPAddServer | Form for manual stdio/sse server configuration. |
| Import/Export | MCPImportExport | Handles JSON file imports and Claude Desktop sync. |
Sources: src/components/MCPManager.tsx:95-125
Tool Widgets
When Claude uses an MCP tool during a session, the MCPWidget provides a specialized visualization of the request, including the namespace, method, and parameters.
// Tool name format: mcp__namespace__method
const parts = toolName.split('__');
const namespace = parts[1] || '';
const method = parts[2] || '';
Sources: src/components/ToolWidgets.tsx:684-690
Conclusion
MCP Server Management is a critical subsystem that enables Opcode to extend the capabilities of Claude Code. By providing a structured way to handle stdio and SSE transports, as well as seamless integration with Claude Desktop, it simplifies the orchestration of the Model Context Protocol within a desktop development environment.