MCP Configuration

Relevant source files

• AGENTS.md
• packages/AGENTS.md
• packages/claude-code-compat-core/src/features/claude-code-mcp-loader/loader.test.ts
• packages/claude-code-compat-core/src/features/claude-code-plugin-loader/types.ts
• packages/omo-opencode/src/agents/AGENTS.md
• packages/omo-opencode/src/agents/prometheus/AGENTS.md
• packages/omo-opencode/src/features/AGENTS.md
• packages/omo-opencode/src/features/boulder-state/AGENTS.md
• packages/omo-opencode/src/features/team-mode/AGENTS.md
• packages/omo-opencode/src/hooks/AGENTS.md
• packages/omo-opencode/src/hooks/auto-update-checker/AGENTS.md
• packages/omo-opencode/src/hooks/keyword-detector/AGENTS.md
• packages/omo-opencode/src/mcp/ast-grep.test.ts
• packages/omo-opencode/src/mcp/ast-grep.ts
• packages/omo-opencode/src/mcp/lsp.test.ts
• packages/omo-opencode/src/mcp/lsp.ts
• packages/omo-opencode/src/mcp/shared/ancestor-cli-resolver.ts
• packages/omo-opencode/src/tools/AGENTS.md
• packages/skills-loader-core/src/features/builtin-skills/git-master/SKILL.md
• packages/skills-loader-core/src/features/builtin-skills/skills/git-master-sections/history-search-workflow.ts
• packages/skills-loader-core/src/features/builtin-skills/skills/git-master-sections/overview.ts
• packages/skills-loader-core/src/features/builtin-skills/skills/git-master-sections/rebase-workflow.ts
• packages/skills-loader-core/src/features/opencode-skill-loader/async-loader.test.ts
• packages/skills-loader-core/src/features/opencode-skill-loader/async-loader.ts
• packages/skills-loader-core/src/features/opencode-skill-loader/blocking.test.ts
• packages/skills-loader-core/src/features/opencode-skill-loader/blocking.ts
• packages/skills-loader-core/src/shared/claude-config-dir.ts

This page documents the Model Context Protocol (MCP) configuration system in oh-my-opencode. The system follows a 3-tier architecture to merge built-in capabilities, local Claude Code configurations, and dynamic skill-embedded servers.

---

Three-Tier MCP Architecture

The system merges MCP servers from three distinct sources. The configuration logic ensures that servers are prioritized, environment variables are expanded, and authentication is handled via OAuth where necessary.

MCP Hierarchy and Data Flow

The following diagram illustrates how the SkillMcpManager and various loaders interact to provide a unified toolset to the agents.

3-Tier MCP Integration Flow

Sources: packages/omo-opencode/src/mcp/AGENTS.md1-20 packages/omo-opencode/src/features/AGENTS.md18-23 packages/claude-code-compat-core/src/features/claude-code-mcp-loader/loader.test.ts11-73

---

Tier 1: Built-in MCPs

Built-in MCPs are core tools provided out-of-the-box. These include both remote search services and local structural analysis tools.

Built-in Catalog

MCP Name	Implementation Package	Purpose
lsp	lsp-tools-mcp	Provides lsp_diagnostics, lsp_goto_definition, etc. packages/AGENTS.md32
ast_grep	ast-grep-mcp	Provides ast_grep_search and ast_grep_replace packages/AGENTS.md33
git_bash	git-bash-mcp	Windows-only tool for Codex edition packages/AGENTS.md34
websearch	Remote	Remote search via Exa or Tavily.

The lsp and ast_grep tools are registered as Tier-1 stdio MCPs, ensuring low-latency access to codebase intelligence packages/omo-opencode/src/tools/AGENTS.md21

Sources: packages/AGENTS.md30-35 packages/omo-opencode/src/tools/AGENTS.md7-21

---

Tier 2: Claude Code MCPs

The system maintains compatibility with the Claude Code ecosystem by scanning for .mcp.json and ~/.claude.json files.

Configuration Discovery

The getSystemMcpServerNames function scans multiple locations in priority order:

1. Project Scope: .mcp.json in the current working directory packages/claude-code-compat-core/src/features/claude-code-mcp-loader/loader.test.ts42-56
2. Local Claude Scope: .claude/.mcp.json packages/claude-code-compat-core/src/features/claude-code-mcp-loader/loader.test.ts75-86
3. User Scope: ~/.claude.json packages/claude-code-compat-core/src/features/claude-code-mcp-loader/loader.test.ts205-216

Higher-precedence configurations (like project-local files) can override or disable servers defined at the user level packages/claude-code-compat-core/src/features/claude-code-mcp-loader/loader.test.ts136-169

Sources: packages/claude-code-compat-core/src/features/claude-code-mcp-loader/loader.test.ts11-254 packages/omo-opencode/src/features/AGENTS.md23

---

Tier 3: Skill-Embedded MCPs

Skills defined in SKILL.md files can embed MCP server definitions. These are managed by the SkillMcpManager within the omo-opencode adapter, utilizing primitives from mcp-client-core packages/omo-opencode/src/features/AGENTS.md18

SkillMcpManager Lifecycle

The manager handles the connection pooling and JSON-RPC dispatch for tools defined within skills. It ensures that servers are only spawned when a tool is actually invoked by an agent.

Skill MCP Tool Execution Flow

Sources: packages/omo-opencode/src/features/AGENTS.md18 packages/AGENTS.md56

---

OAuth Authentication for MCP

For enterprise or protected remote MCP servers, the system implements a robust OAuth 2.0 flow. This feature is integrated into the mcp-oauth module and mcp-client-core packages/omo-opencode/src/features/AGENTS.md21

OAuth Implementation Details

• Standards Support: Implements OAuth 2.0 with PKCE and Dynamic Client Registration (DCR - RFC 7591) packages/omo-opencode/src/features/AGENTS.md21
• Step-up Auth: Supports "step-up" authentication, where a session can escalate permissions at runtime if an MCP server requires higher authorization packages/omo-opencode/src/features/AGENTS.md21
• CLI Integration: Users can manage their MCP identities via oh-my-opencode mcp-oauth commands packages/omo-opencode/src/AGENTS.md63

Sources: packages/omo-opencode/src/features/AGENTS.md21 packages/omo-opencode/src/AGENTS.md60-63

---

Connection Management and Security

Environment Expansion

The system supports ${VAR} style environment expansion in MCP configurations. This is handled by the claude-code-mcp-loader adapter shims packages/omo-opencode/src/features/AGENTS.md23

Security Constraints

• Untrusted Project Configs: Project-level .mcp.json files are treated with restricted permissions to prevent malicious command execution during discovery.
• Redaction: Sensitive keys and tokens are redacted from logs and error messages.

Resource Cleanup

• Idle Detection: stdio MCP processes are monitored for idleness.
• Session Disposal: All active MCP clients associated with a session are terminated when the session is closed.
• LSP Daemon: For lsp tools, the lsp-daemon package allows multiple sessions to share a single warm LSP process via unix sockets/named pipes, significantly reducing startup overhead packages/AGENTS.md35

Sources: packages/omo-opencode/src/features/AGENTS.md23 packages/AGENTS.md35 packages/AGENTS.md52