How to Configure MCP Servers in AI Coding Assistants Like OpenCode

Mar 19, 2026

I added an MCP server to my OpenCode config, restarted the app, and nothing happened. No tools showed up. No error messages. Just silence.

After digging through documentation, Reddit threads, and way too many JSON syntax validators, I figured out what I was doing wrong. The configuration itself wasn’t hard - but finding where to put it and getting the syntax right took way longer than it should have.

The Problem: Config File Confusion

Here’s what tripped me up:

Different AI assistants use different config file locations
The JSON structure has to be exactly right or it silently fails
Environment variables need special handling
There’s no UI for this - it’s all manual file editing

A Reddit post about NeoCode (a Mac-native OpenCode alternative) confirmed I wasn’t alone. The developer mentioned that MCP configuration through settings UI is “next on my list” - meaning everyone is currently stuck editing JSON files by hand.

Finding Your Config File

The first hurdle: where does the config file actually live?

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)

If the file doesn’t exist, create it. But create it in the right place - I initially put mine in ~/.config/opencode/ and wondered why nothing worked.

The Basic Structure

An MCP configuration file looks like this:

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-name"],
      "env": {}
    }
  }
}

The key things to remember:

Everything goes inside mcpServers
Each server is a named object
command is the executable (usually npx or python)
args is an array of arguments
env contains environment variables

My First Working Configuration

I started simple - just the filesystem server:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/cowrie/projects"
      ]
    }
  }
}

The -y flag is important - it tells npx to automatically install the package if it’s not cached. Without it, npx will prompt for confirmation, which fails silently in non-interactive contexts.

After saving this file and restarting OpenCode, I finally saw the filesystem tools appear. Progress.

Adding Environment Variables

The next challenge: servers that need API keys. I tried this first:

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

This works, but it’s a bad idea. Your API keys end up in a plain text file that might get committed to dotfiles repos or shared configurations.

The better approach:

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

Then export the variable in your shell:

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

This way, the config file is safe to share, and you manage secrets through your shell environment.

Multiple Servers Together

Once I got individual servers working, I combined them:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/cowrie/projects"
      ]
    },
    "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}"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://localhost/myapp"
      }
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

The memory server is nice - no setup required, just add it and your AI assistant can persist information across conversations.

Python-Based MCP Servers

Not all MCP servers are npm packages. Some are Python scripts:

{
  "mcpServers": {
    "custom-tools": {
      "command": "python",
      "args": ["/Users/cowrie/mcp-servers/my_tools.py"],
      "env": {
        "PYTHONPATH": "/Users/cowrie/mcp-servers/lib"
      }
    }
  }
}

For Python servers, make sure:

python is in your PATH (or use the full path like /usr/bin/python3)
All dependencies are installed in the environment Python will use
The script is executable if needed

Common Servers and What They Need

Server                    | Purpose              | Required Setup
--------------------------|---------------------|---------------------------
server-filesystem         | File operations     | Path argument
server-github            | GitHub API          | GITHUB_TOKEN env var
server-postgres          | PostgreSQL          | DATABASE_URL env var
server-brave-search      | Web search          | BRAVE_API_KEY env var
server-memory            | Persistent memory   | Nothing required
server-slack             | Slack integration   | Slack bot tokens

Debugging When Things Go Wrong

My MCP servers didn’t show up. Here’s how I debugged:

Check 1: JSON Syntax

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

If this errors, your JSON is malformed. Common issues:

Missing commas between server entries
Trailing commas (not allowed in JSON)
Unquoted keys or values

Check 2: Command Availability

npx -y @modelcontextprotocol/server-filesystem /tmp/test

If this fails outside OpenCode, it’ll fail inside too.

Check 3: Environment Variables

echo $GITHUB_TOKEN
echo $BRAVE_API_KEY

If these are empty, the MCP servers will start but fail when they try to use the APIs.

Check 4: Logs

# OpenCode logs
tail -f ~/.opencode/logs/mcp.log

# Or check the main log
tail -f ~/.opencode/logs/main.log | grep -i mcp

The logs often show connection errors or authentication failures that the UI doesn’t display.

Mistakes I Made

Mistake 1: Wrong Config Location

I created my config in ~/.config/opencode/config.json instead of ~/.opencode/config.json. OpenCode doesn’t look in multiple locations - it expects one specific path.

Mistake 2: Missing the `-y` Flag

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem", "/projects"]
    }
  }
}

This silently failed because npx wanted confirmation but couldn’t get it. Always add -y.

Mistake 3: Conflicting Server Names

I had two configs with "filesystem" as the key:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/projects"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/documents"]
    }
  }
}

The second one overwrote the first. Use unique names.

Verifying Your Setup

After configuring, restart OpenCode completely (not just reload). Then:

Start a new conversation
Look for MCP tools in the available functions
Test with a simple operation

User: List files in /Users/cowrie/projects
Assistant: [Should use the filesystem tool to list files]

If the assistant uses the tool, your MCP is working. If it tries to “pretend” or makes up paths, something’s wrong.

The Future: GUI Configuration

The Reddit discussion about NeoCode revealed that better UX is coming. The NeoCode developer said:

“Next on my list is internationalization… and then probably the ability to actually modify your OpenCode config through the settings page (including MCPs).”

This means:

No more manual JSON editing
Server discovery and one-click setup
Real-time status monitoring
Better error messages

But for now, manual configuration is the only option.

Summary

Getting MCP servers working in OpenCode:

Find the right config file - Usually ~/.opencode/config.json
Create the mcpServers object - All servers go inside this
Add your servers - Command, args, env for each
Use -y with npx - Avoid interactive prompts
Reference env vars, don’t hardcode - ${VARIABLE_NAME} syntax
Restart completely - Changes need a full restart
Check logs if things fail - ~/.opencode/logs/mcp.log

The MCP ecosystem is growing fast. New servers appear weekly for databases, APIs, and services. Once you understand the configuration pattern, adding new capabilities to your AI assistant becomes straightforward - even if the process is still more manual than it should be.

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:

👨‍💻 Model Context Protocol Documentation
👨‍💻 OpenCode GitHub Repository
👨‍💻 MCP Server Registry
👨‍💻 Anthropic Claude Documentation

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