MCP Servers

The Model Context Protocol (MCP) connects opencode to external tools and services. MCP servers expose capabilities like database queries, issue tracker operations, API calls, and cloud service management directly to the AI model.

Overview

Configuring MCP Servers

MCP servers are configured in opencode.json under the mcp key:

{
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": false
    },
    "postgres": {
      "type": "command",
      "command": "node",
      "args": ["path/to/mcp-postgres-server.js"],
      "enabled": true
    },
    "filesystem": {
      "type": "command",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"],
      "enabled": true
    }
  }
}

Server Types

Type	Description	Example
remote	HTTP/S server hosted externally	Cloud-hosted MCP service
command	Local process launched by opencode	Database server, FS access

Configuration Fields

Field	Type	Required	Description
type	string	Yes	"remote" or "command"
url	string	For remote	Base URL of the MCP server
command	string	For command	Executable to run
args	string[]	For command	Arguments for the executable
enabled	boolean	No	Whether the server is active (default: true)
env	object	No	Environment variables for command servers

Managing MCP Servers via CLI

opencode provides CLI commands to manage MCP servers interactively.

Adding a Server

The interactive wizard walks you through configuration:

opencode mcp add

Prompts:

1. Server name — A unique identifier (e.g., jira, postgres).
2. Server type — remote or command.
3. Connection details — URL for remote, command + args for local.
4. Environment variables — Optional environment overrides.

The new server is added to opencode.json automatically.

Listing Servers

View all configured MCP servers:

opencode mcp list

Or the shorter alias:

opencode mcp ls

Output shows the server name, type, status (enabled/disabled), and a brief description.

opencode mcp auth jira

This initiates an OAuth flow:

1. A browser opens to the MCP server's authorization endpoint.
2. You grant permissions.
3. Credentials are stored securely by opencode.

Logging Out

Remove stored credentials for an OAuth-authenticated MCP server:

opencode mcp logout jira

This clears the stored tokens without removing the server configuration.

Debugging

Troubleshoot an MCP server connection:

opencode mcp debug postgres

This command:

1. Attempts to connect to the server.
2. Lists available tools and resources.
3. Invokes a health-check operation if available.
4. Displays any connection errors or configuration issues.

Output includes:

Server: postgres
Type: command
Status: connected
Tools:
  - query (args: sql)
  - list_tables (args: schema)
  - describe_table (args: table)
Resources:
  - postgres://schemas
  - postgres://tables

Use Cases

tip

Use the permissions system to control which MCP tools the model can invoke without confirmation.

{
  "mcp": {
    "database": {
      "type": "command",
      "command": "npx",
      "args": ["-y", "@anthropic/server-postgres", "postgresql://user:pass@host:5432/db"],
      "enabled": true
    }
  }
}

Issue Trackers

Integrate with Jira, Linear, or GitHub Issues:

{
  "mcp": {
    "linear": {
      "type": "remote",
      "url": "https://linear-mcp.example.com",
      "enabled": true
    }
  }
}

The model can create, update, and search issues directly.

Internal APIs

Connect to your organization's internal services:

{
  "mcp": {
    "deploy-api": {
      "type": "remote",
      "url": "https://deploy.internal.corp/mcp",
      "enabled": true,
      "env": {
        "API_KEY": "${DEPLOY_API_KEY}"
      }
    }
  }
}

Cloud Services

Manage cloud infrastructure through MCP:

{
  "mcp": {
    "aws": {
      "type": "command",
      "command": "npx",
      "args": ["-y", "@anthropic/server-aws"],
      "enabled": true
    }
  }
}

{
  "permissions": {
    "mcp": {
      "database_query": "allow",
      "database_drop_table": "deny"
    }
  }
}

You can use wildcard patterns:

{
  "permissions": {
    "mcp": {
      "mymcp_*": "deny",
      "mymcp_read": "allow"
    }
  }
}

Permission values:

Value	Effect
"allow"	The model can invoke this tool freely
"deny"	The model cannot invoke this tool
"ask"	opencode prompts for confirmation before each invocation

# mcp_server.py
import json
import sys

def handle_request(request):
    if request["method"] == "tools/list":
        return {
            "tools": [
                {
                    "name": "greet",
                    "description": "Greet a user",
                    "inputSchema": {
                        "type": "object",
                        "properties": {
                            "name": {"type": "string"}
                        },
                        "required": ["name"]
                    }
                }
            ]
        }
    elif request["method"] == "tools/call":
        tool = request["params"]["name"]
        args = request["params"]["arguments"]
        if tool == "greet":
            return {"content": f"Hello, {args['name']}!"}
    return {"error": "unknown method"}

for line in sys.stdin:
    request = json.loads(line)
    response = handle_request(request)
    print(json.dumps(response), flush=True)

Configure it:

{
  "mcp": {
    "greeter": {
      "type": "command",
      "command": "python3",
      "args": ["/path/to/mcp_server.py"],
      "enabled": true
    }
  }
}

note

Command-type MCP servers must be installed and available on your system PATH before opencode can launch them.

Troubleshooting

Server Not Connecting

• Verify the URL is reachable from your network.
• For command-type servers, ensure the command is installed and on your PATH.
• Check environment variables are correctly configured.

Tools Not Appearing

• The server may not have started successfully. Run opencode mcp debug <name>.
• Check that enabled is not set to false.

Authentication Errors

• Run opencode mcp auth <name> to re-authenticate.
• Verify the OAuth application is still valid.
• Check token expiry dates.

Permission Denied

• If the model reports a tool is unavailable, check your permission rules in opencode.json.
• Ensure the wildcard pattern does not accidentally deny the tool.