OpenCode Configuration Man Page

README.md

Quick Start

Get started with OpenCode directly from your terminal using npx or bunx. No installation required.

# Run with npx (Node.js)
npx opencode-ai@latest

# Or run with bunx (Bun)
bunx opencode-ai@latest

Once inside the interactive session:

1. Connect a Provider

Use the /connect command to authenticate with your preferred LLM provider. OpenCode supports a wide range of providers including:

• OpenAI
• Anthropic
• OpenRouter
• Groq
• Google Vertex

> /connect

Select your provider from the list and enter your API key when prompted.

2. Select a Model

After connecting, use /models to choose the specific model you want to power your coding agent (e.g., gpt-4o, claude-3-5-sonnet, deepseek-r1 etc.).

> /models

For advanced configuration, including MCP Servers, see the man page OPENCODE-MCP(5) included in this gist.

OPENCODE-MCP.5

OPENCODE-MCP(5)                    OpenCode Configuration                   OPENCODE-MCP(5)

NAME
       opencode-mcp - configure Model Context Protocol servers in OpenCode

SYNOPSIS
       ~/.config/opencode/opencode.json
       ./opencode.json (project-specific)

DESCRIPTION
       OpenCode supports integration of external tools via the Model Context Protocol
       (MCP). MCP servers extend OpenCode's capabilities by providing additional tools
       and data sources to the LLM.

       Configuration is defined in JSON format under the "mcp" key. Both global and
       project-level configurations are supported and merged together, with project-level
       settings taking precedence.

CONFIGURATION STRUCTURE
       {
         "$schema": "https://opencode.ai/config.json",
         "mcp": {
           "server-name": {
             "type": "local" | "remote",
             ...server-specific options...
           }
         }
       }

LOCAL SERVERS
       Local MCP servers are started as child processes when OpenCode initializes.
       These are typically Node.js packages, Python scripts, or compiled binaries.

       type
           Must be set to "local".

       command (required)
           Array of strings specifying the command and arguments to execute.
           Example: ["bunx", "-y", "package-name"]
           Example: ["npx", "-y", "@namespace/package"]
           Example: ["python", "-m", "module_name"]

       environment (optional)
           Object containing environment variables to pass to the process.
           Keys are variable names, values are strings.
           Example:
             "environment": {
               "API_KEY": "sk-...",
               "DEBUG": "true"
             }

       enabled (optional)
           Boolean. Defaults to true. Set to false to disable the server on startup
           without removing its configuration.

       timeout (optional)
           Number in milliseconds. Defaults to 5000 (5 seconds).
           Maximum time to wait for the server to provide its tool list.

REMOTE SERVERS
       Remote MCP servers are accessed via HTTP endpoints. Typically these are
       long-running services or cloud-hosted MCP implementations.

       type
           Must be set to "remote".

       url (required)
           String. The HTTP URL of the MCP server endpoint.
           Example: "https://mcp.example.com/mcp"
           Example: "http://localhost:8765/sse"

       headers (optional)
           Object containing HTTP headers to send with requests.
           Commonly used for authentication.
           Example:
             "headers": {
               "Authorization": "Bearer token-value",
               "X-API-Key": "key-value"
             }

       enabled (optional)
           Boolean. Defaults to true. Set to false to disable without removing config.

       timeout (optional)
           Number in milliseconds. Defaults to 5000 (5 seconds).

ENVIRONMENT VARIABLE SUBSTITUTION
       Values in configuration can reference environment variables using the syntax:
       "{env:VARIABLE_NAME}"

       Example:
         "headers": {
           "Authorization": "Bearer {env:MY_API_KEY}"
         }

       The variable must be set in the shell environment before running OpenCode.

EXAMPLES
       Context7 (Remote Service)
       ───────────────────────────
       {
         "mcp": {
           "context7": {
             "type": "remote",
             "url": "https://mcp.context7.com/mcp",
             "headers": {
               "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}"
             }
           }
         }
       }

       Tavily Search (Local via bunx)
       ──────────────────────────────
       {
         "mcp": {
           "tavily": {
             "type": "local",
             "command": ["bunx", "-y", "tavily-mcp@latest"],
             "environment": {
               "TAVILY_API_KEY": "xxxxxxxx"
             }
           }
         }
       }

       Local SSE Endpoint
       ──────────────────
       {
         "mcp": {
           "excel-analysis": {
             "type": "remote",
             "url": "http://localhost:8765/sse"
           }
         }
       }

       Multiple Servers (Combined)
       ───────────────────────────
       {
         "$schema": "https://opencode.ai/config.json",
         "mcp": {
           "context7": {
             "type": "local",
             "command": ["bunx", "-y", "@upstash/context7-mcp", "--api-key", "xxxxxxxx"]
           },
           "tavily": {
             "type": "local",
             "command": ["bunx", "-y", "tavily-mcp@latest"],
             "environment": {
               "TAVILY_API_KEY": "xxxxxxxx"
             }
           },
           "excel-analysis": {
             "type": "remote",
             "url": "http://localhost:8765/sse"
           }
         }
       }

USAGE
       After configuring MCP servers, reference them in prompts using:

       "use context7"
       "use tavily"
       "use the excel-analysis tool"

       Or add instructions to AGENTS.md in your project root:

       When searching documentation, use `context7` tools.
       When you need web search, use `tavily` tools.

VALIDATION
       OpenCode validates the configuration on startup. If the config is invalid,
       error messages will indicate which keys are problematic:

       Config file at ~/.config/opencode/opencode.json is invalid
       ↳ Invalid input mcp.context7.type

       Common issues:
       - Missing required "type" field
       - Invalid "type" value (must be "local" or "remote")
       - Missing "command" for local servers
       - Missing "url" for remote servers
       - Malformed JSON syntax

CONFIGURATION FILES
       Global Configuration
           ~/.config/opencode/opencode.json
           Applied to all OpenCode invocations for the user.

       Project Configuration
           ./opencode.json in the project root
           Merged with global config; project settings override global settings.
           Recommended to commit to version control.

CONTEXT AND PERFORMANCE
       Each MCP server adds to the LLM context window. Using many MCP servers
       simultaneously can quickly exhaust available context tokens. Enable only
       the servers you actually need for a given task.

       Use the "enabled: false" option to keep configurations while disabling
       servers temporarily.

SEE ALSO
       OpenCode documentation: https://opencode.ai/docs/mcp-servers/
       Model Context Protocol: https://modelcontextprotocol.io/

AUTHOR
       Simon

OPENCODE                                                               OPENCODE-MCP(5)