MCP SERVER
Full lifecycle management for IDE configuration — servers, agents, permissions, plugins, commands, and instructions through validated tool calls.
| Tool | Purpose | Returns |
|---|---|---|
| diagnose | Assess workspace against the ecosystem manifest — repos cloned, deps installed, servers registered. Findings sorted by severity with actionable fix commands. | Findings array, tier stats, severity summary |
| sanitize | Detect and remove config rot — dead servers, orphaned permissions, phantom agents, broken symlinks, stale instructions, duplicates. Dry-run by default. | Rot inventory by category, cleanup results |
| show | Full resolved config — opencode.json, agents, plugins, servers. The complete picture in one call. | Merged config object with all sources |
| validate | Structural validation of opencode.json with path existence checks for plugins, servers, and instruction files. | Validation results, path existence flags |
| ensure_local | Audit global vs project config sources. Surface settings that differ between teammates due to personal global configs. | Per-level config contributions, divergences |
| list_servers | List all MCP servers with enabled/disabled status, type, and command | Server entries with metadata |
| add_server | Add a new server entry (local or remote). Also creates the corresponding permission rule automatically. | Server entry, permission created |
| update_server | Merge-update server fields — command, url, environment, enabled, type. Null values in environment remove individual keys. | Updated server entry |
| remove_server | Remove a server entry and its permission rule in one operation | Removal confirmation |
| enable_server | Enable a disabled server without touching other fields | Updated status |
| disable_server | Disable a server without removing it from config | Updated status |
| list_agents | List all agents from opencode.json and .opencode/agents/ with status, mode, and color. Merges both sources. | Agent entries with source attribution |
| get_agent | Read a single agent's full content — config entry, YAML frontmatter, and prompt body. | Agent config, frontmatter, body text |
| set_agent | Create or update an agent — writes .opencode/agents/{name}.md with YAML frontmatter for model, mode, color, temperature, steps. | File path, frontmatter written |
| set_default_agent | Set the default_agent field in opencode.json | Updated config value |
| enable_agent | Re-enable a disabled agent by removing the disable flag | Updated status |
| disable_agent | [object Object] | Updated status |
| remove_agent | Delete the agent .md file and config block. Clears default_agent if matched | Removal confirmation |
| list_permissions | List all permission rules from opencode.json | Permission entries with patterns and values |
| set_permission | Set a permission rule — pattern (e.g. bash, scout_*) to allow, deny, or ask. Supports nested sub-patterns for bash commands. | Updated permission entry |
| remove_permission | Remove a permission rule. Returns the previous value for confirmation | Previous value, removal confirmation |
| list_commands | List all slash commands from .opencode/commands/ | Command entries with descriptions |
| get_command | Read a single command's description and instruction body | Command frontmatter and body |
| set_command | Create or update a slash command — writes .opencode/commands/{name}.md with instructions injected on trigger. | File path, command registered |
| remove_command | Delete a slash command file | Removal confirmation |
| list_plugins | List all registered plugins — directory entries from plugin array and individual files from .opencode/plugins/. Shows symlink status and hook inventory. | Plugin entries with symlink targets, hooks |
| add_plugin | Register a plugin directory in opencode.json. Validates path exists | Registration confirmation |
| unregister_plugin | Remove a plugin directory from opencode.json. Does not delete files | Removal confirmation |
| link_plugin | Symlink a plugin .ts file from a repo into .opencode/plugins/. Idempotent — re-linking same target is a no-op. | Link path, target, status |
| unlink_plugin | Remove a plugin symlink. Source file in its repo is preserved | Removal confirmation |
| list_instructions | List all instruction files from opencode.json with existence check | Instruction paths with exists flags |
| add_instruction | Add an instruction file to the instructions array. Validates file exists | Updated instructions array |
| remove_instruction | Remove an instruction file from the array | Removal confirmation |
| set_config | Set a config value by dotted path (e.g. compaction.auto, model). Rejects invalid JSON, blocks writes to managed sections. | Updated config value |
| export_config | Export full config as a portable v2 bundle — config, agents, commands, instruction contents, plugin symlink metadata. | Bundle path, counts per category |
| import_config | Import a config bundle. Supports dry-run preview, overwrite control, backward-compatible with v1 bundles. | Import results, per-category counts |
An MCP server ecosystem needs configuration to run — but the configuration itself is complex. opencode.json manages servers, agents, permissions, plugins, commands, and instructions across multiple file locations. Manual editing is error-prone: a typo in a server command silently breaks it, a removed repo leaves orphaned permissions, a disabled agent accumulates dead config. opencode-config replaces manual editing with validated, atomic tool calls that enforce consistency across all config surfaces.
Configuration is scattered across opencode.json (servers, permissions, general settings), .opencode/agents/ (agent .md files with YAML frontmatter), .opencode/commands/ (slash command definitions), .opencode/plugins/ (symlinked plugin files), and the plugin array (directory-based plugins). Each domain has its own CRUD tools, but they all operate through the same shared config I/O layer — readConfig/writeConfig with atomic JSON serialization and 2-space indent normalization.
The manifest.yaml file declares the entire ecosystem — every server, its tier, repo URL, entry file, and dependencies. diagnose walks this manifest against the actual workspace state. Missing repos, uninstalled dependencies, unregistered servers, disabled core tools — each finding comes with a severity level and an actionable fix command. The /setup command runs diagnose as its first step.
Config rot accumulates silently. A server repo gets deleted but its config entry stays. An agent gets disabled but its .md file lingers. A plugin symlink points to a moved file. Sanitize detects nine categories of rot — stale servers, orphaned permissions, phantom agents, broken symlinks, stale instructions, duplicates, missing permissions, dead servers, and disabled agent files. Dry-run by default so you see the rot before cleaning it.
A v2 bundle captures the full config state — opencode.json, agent files with frontmatter and prompts, command definitions, instruction file contents, plugin symlink metadata, and a server manifest. Import reconstructs everything on a fresh machine, recreating symlinks when targets exist on disk. Backward-compatible with v1 bundles. Dry-run preview before applying.
mcp-helpers — server bootstrap, workspace() resolution, and the respond/error response helpers shared by all servers. yaml — parses the ecosystem manifest.yaml that diagnose walks. zod — parameter validation for all 36 tools. No runtime dependency on other MCP servers. opencode-config reads opencode.json directly from disk.
Every MCP server is registered and managed through opencode-config's server tools. The /setup onboarding command uses diagnose to assess workspace health and add_server to register missing servers. plugin-builder scaffolds plugin files that opencode-config then symlinks into .opencode/plugins/ via link_plugin. The manifest.yaml is the ecosystem's source of truth — other tools reference it for server metadata.
The server that configures the servers that configure the servers.