Skip to content
BSWEN
Blog

How to Configure MCP Servers in OpenCode Settings

Cowrie
Cowrie
Dev @ Bswen

Problem

I wanted to add MCP servers to OpenCode to extend its capabilities. I opened the settings, looked through every menu, and found nothing. No “Add MCP Server” button. No server management UI. Nothing.

Here’s what I was trying to do:

My Goal
OpenCode -> Settings -> MCP Servers -> Add Server
                                        [Not Found]

I checked the documentation, searched GitHub issues, and eventually found the answer: OpenCode doesn’t have a GUI for MCP configuration yet. You have to edit the config file manually.

What happened?

I discovered this pain point through a Reddit discussion about NeoCode (a Mac-native OpenCode desktop replacement). The author mentioned:

“Next on my list is internationalization so I can provide a good experience for non-English speakers, and then probably the ability to actually modify your OpenCode config through the settings page (including MCPs).”

This told me two things:

  1. MCP configuration is a highly requested feature
  2. Currently, manual config file editing is the only option

So I set out to learn how to configure MCP servers the “hard way.”

Finding the Config File

First, I needed to locate where OpenCode stores its configuration. After some digging, I found it:

Config File Locations
OpenCode:      ~/.opencode/config.json
Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
NeoCode:       ~/.config/neocode/config.json
VS Code MCP:   .vscode/mcp.json (project-level)

I checked if the file existed:

Terminal window
ls -la ~/.opencode/config.json

Output:

Terminal window
ls: cannot access '/Users/username/.opencode/config.json': No such file or directory

The file didn’t exist. I needed to create it.

Creating the Configuration

I created the directory and file:

Terminal window
mkdir -p ~/.opencode
touch ~/.opencode/config.json

Then I looked up the MCP server configuration format. The basic structure is:

~/.opencode/config.json
{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-package"],
      "env": {}
    }
  }
}

My First Attempt: Filesystem Server

I started with the filesystem MCP server - a simple one that gives the AI access to files:

~/.opencode/config.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/projects"
      ]
    }
  }
}

I restarted OpenCode and… nothing. The server didn’t appear.

Debugging the Configuration

I checked if npx was available:

Terminal window
which npx

Output:

Terminal window
/usr/local/bin/npx

npx was there. Then I tried running the MCP server directly:

Terminal window
npx -y @modelcontextprotocol/server-filesystem /Users/username/projects

Output:

npm ERR! could not determine executable to run
npm ERR! A complete log of this run can be found in:
npm ERR!     /Users/username/.npm/_logs/2026-03-19T10_00_00_000Z-debug.log

The package name was wrong. I checked the official MCP server registry and found the correct package name:

Terminal window
npx -y @modelcontextprotocol/server-filesystem /Users/username/projects

This time it worked. The server started and waited for input on stdin.

Correct Configuration Format

I realized my config was correct, but I needed to restart OpenCode properly. After a full restart, the MCP server loaded successfully.

Here’s the working configuration:

~/.opencode/config.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/projects"
      ],
      "env": {}
    }
  }
}

Adding Multiple MCP Servers

Next, I wanted to add GitHub integration and web search. Here’s what I learned about environment variables:

MCP Server Types
+------------------+----------------------------------------+
| Server           | Purpose                                |
+------------------+----------------------------------------+
| server-filesystem| File system access (path arg required) |
| server-github    | GitHub API operations (token required)|
| server-postgres  | PostgreSQL queries (DB URL required)   |
| server-brave-search| Web search (API key required)        |
| server-memory    | Conversation memory (no setup)        |
| server-slack     | Slack integration (bot tokens req)    |
+------------------+----------------------------------------+

Environment Variable Mistake

My first attempt at adding GitHub:

WRONG: Hardcoded Token
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

This works, but it’s a security risk. The token gets stored in plain text.

The correct approach is to reference environment variables from the shell:

CORRECT: Reference Shell Environment
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Then set the token in the shell:

~/.zshrc or ~/.bashrc
export GITHUB_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxx"

My Final Configuration

After several iterations, here’s my working multi-server configuration:

~/.opencode/config.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/projects"
      ],
      "env": {}
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "${BRAVE_API_KEY}"
      }
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"],
      "env": {}
    }
  }
}

Troubleshooting Guide

MCP Server Not Loading

I encountered several issues. Here’s my troubleshooting checklist:

Troubleshooting Steps
1. Check JSON syntax with a validator
2. Verify npx is in PATH: which npx
3. Test server directly: npx -y @package/name args
4. Check for conflicting server names
5. Restart OpenCode completely (not just reload)

Verifying Server Status

To check if an MCP server is working:

Test MCP Server Independently
npx -y @modelcontextprotocol/server-filesystem /tmp/test

If the server starts without errors, the configuration should work.

Common Error Patterns

Error: npm ERR! could not determine executable to run

This means the package name is wrong. Check the official MCP server registry for correct names.

Error: Cannot find module

The package might not be published yet or the name is incorrect.

Error: Permission denied

Check file permissions:

Terminal window
ls -la ~/.opencode/config.json

Server doesn’t appear in OpenCode

Check the JSON syntax:

Terminal window
cat ~/.opencode/config.json | python3 -m json.tool

If this fails, there’s a syntax error.

Python-based MCP Servers

I also wanted to add a custom Python-based MCP server. The configuration is different:

Python MCP Server Configuration
{
  "mcpServers": {
    "custom-server": {
      "command": "python",
      "args": ["/path/to/my_mcp_server.py"],
      "env": {
        "PYTHONPATH": "/path/to/modules"
      }
    }
  }
}

For Python servers, make sure:

Python Server Checklist
1. Python is in PATH
2. Virtual environment is activated (if using one)
3. All dependencies are installed
4. The script has execute permissions: chmod +x server.py

Why MCP Configuration Matters

MCP (Model Context Protocol) servers extend what AI assistants can do:

MCP Server Capabilities
+------------------+-----------+----------------------------------+
| Type             | Provides  | Example Use Case                 |
+------------------+-----------+----------------------------------+
| Tool Servers     | Functions | File operations, API calls       |
| Resource Servers | Data      | Database queries, file reading   |
| Prompt Servers   | Templates | Reusable prompt patterns         |
+------------------+-----------+----------------------------------+

Without MCP servers, AI assistants are limited to:

  • Reading/writing files you explicitly share
  • Basic web searches (if available)
  • Code generation based on context alone

With MCP servers, they can:

  • Query databases directly
  • Interact with GitHub APIs
  • Search the web with Brave Search
  • Maintain conversation memory
  • Access project-specific tools

Future: GUI Configuration

Based on the Reddit discussion, GUI configuration is coming. NeoCode and similar apps are working on:

Upcoming Features
1. Settings Page Integration - No more manual JSON editing
2. Server Discovery - Browse available MCP servers
3. One-Click Setup - Automatic environment variable detection
4. Health Monitoring - Real-time MCP server status

Until then, manual configuration remains the only option.

Summary

In this post, I showed how to configure MCP servers in OpenCode by editing the config file directly. The key steps are:

  1. Locate or create ~/.opencode/config.json
  2. Add server entries with command, args, and env
  3. Set environment variables in shell (not hardcoded in config)
  4. Restart OpenCode to load the new configuration
  5. Verify by testing the server independently

The configuration format is straightforward once you know where to look. The main challenges are discovering the correct package names and handling environment variables securely.

Quick Reference
Config location: ~/.opencode/config.json
Server registry: github.com/modelcontextprotocol/servers
Test command: npx -y @package/name args

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!

Comments

Tags: