OpenCode MCP (Model Context Protocol)

MCP (Model Context Protocol) is the foundation that allows OpenCode to connect AI models with external tools, services, and long-running context.

This page is the authoritative MCP hub for OpenCode.
It explains what MCP is, why it matters, how it works, and how to configure and use it effectively.

If you are looking for:

How OpenCode connects to tools like file systems or APIs
How to configure MCP servers
How MCP compares to built-in tool systems in other editors

You are in the right place.

What is MCP?

MCP (Model Context Protocol) is a standardized protocol that enables AI clients to communicate with external servers that expose structured capabilities.

Instead of hard-coding tools into the editor, MCP allows OpenCode to:

Discover available tools dynamically
Invoke them in a controlled, inspectable way
Maintain structured context across multiple interactions

In practice, MCP turns OpenCode into a tool-oriented AI environment, not just a chat interface.

Why OpenCode Uses MCP

Traditional AI coding tools rely on tightly coupled, editor-specific integrations.

OpenCode takes a different approach.

By adopting MCP, OpenCode achieves:

Extensibility: Add new capabilities without modifying core editor logic
Transparency: MCP servers run as explicit processes you can inspect and debug
Local-first workflows: Use local models and tools without vendor lock-in
Consistency: The same MCP server can be reused across workflows

This design makes OpenCode especially powerful for advanced and repeatable development workflows.

MCP Architecture Overview

At a high level, MCP consists of three parts:

MCP Client (OpenCode)
Responsible for discovering servers, sending requests, and managing context.
MCP Servers
External processes that expose tools and capabilities via MCP.
Transport & Protocol
A standardized message format that defines how clients and servers communicate.

OpenCode (Client)
↓
MCP Protocol
↓
MCP Server (Tool / Data / API)

Each MCP server focuses on a single responsibility, such as code analysis, file access, or data processing.

Quick Start

Most users can get started with MCP in OpenCode in just a few steps.

1. Install Required Runtime

Depending on the MCP server you want to use, ensure you have:

Node.js (for JavaScript-based servers)
Python (for data or ML-focused servers)

2. Create MCP Configuration File

Create or edit your MCP configuration file (commonly config.json).

3. Restart OpenCode

Restart OpenCode so the MCP client can load and register the servers.

Once loaded, MCP servers become available to OpenCode workflows automatically.

MCP Configuration Example

Below is a minimal MCP configuration example suitable for most local setups.

{
  "mcpServers": {
    "example-server": {
      "command": "node",
      "args": ["./server.js"]
    }
  }
}

Explanation of Key Fields

mcpServers A map of named MCP server definitions.
command The executable used to start the MCP server.
args Arguments passed to the command.

This configuration is sufficient for most local MCP server setups.

MCP Server Configuration

MCP servers can expose a wide range of capabilities, including:

Code analysis and refactoring
Data access and transformation
File system operations
External API integrations

Typical server implementations include:

Node.js servers for JavaScript-based tooling
Python servers for data processing or machine learning workflows

Each MCP server should focus on a clear responsibility and expose a stable interface.

MCP Client Usage Examples

Once configured, MCP servers can be used in OpenCode workflows to:

Fetch structured or external data
Execute repeatable tasks
Maintain long-running context across interactions

MCP is particularly effective for:

Multi-step workflows
Refactoring or analysis pipelines
Tool-heavy development tasks

Common MCP Errors & Troubleshooting

MCP Server Not Responding

Ensure the MCP server process is running
Check command paths and execution permissions
Verify that the server starts without runtime errors

MCP Configuration File Not Loaded

Confirm the configuration file path is correct
Validate JSON syntax
Restart OpenCode after making changes

Permission or Execution Errors

Check executable permissions
Ensure required runtimes (Node.js, Python) are installed
Run the MCP server manually to inspect startup errors

Next Steps

Explore Real-World MCP Use Cases
Compare MCP support in OpenCode vs Claude Code
Learn how to Configure MCP Servers

This page will continue to evolve as MCP support in OpenCode expands.

Introduction

Getting Started

Guides & Integrations

Comparisons