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

MCP is an open protocol that standardizes how AI applications interact with external systems. An MCP server exposes a set of tools, resources, and prompts. opencode can invoke these tools during a session, enabling the model to interact with your infrastructure in real time.

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.

Authentication

Some remote MCP servers use OAuth for authentication.

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

Database Access

Connect opencode to a PostgreSQL or SQLite database. The model can inspect schemas, run queries, and analyse results.

{
  "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
    }
  }
}

Permission Gating

opencode allows you to control which MCP tools the model can invoke using permission rules in opencode.json:

{
  "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 Development

You can build custom MCP servers. The protocol is language-agnostic. A minimal Python server:

# 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
    }
  }
}

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.

Security Considerations

• MCP servers have the same access as the user running them. Restrict command servers to necessary tools.
• Remote MCP servers should use HTTPS with valid certificates.
• Use environment variables for sensitive credentials rather than hardcoding them in configuration.
• Apply permission rules proactively — allow specific tools rather than denying after the fact.
• Regularly audit your MCP configuration and remove unused servers.