Key insight: The MCP ecosystem is growing fast — there's likely already a package for whatever tool you want to connect. The hardest part is usually getting credentials set up correctly the first time. Get one MCP working and the pattern repeats for everything else.
How MCP config works in OpenCode
MCPs are configured in your global OpenCode config file: ~/.config/opencode/opencode.json. All MCP definitions live inside a top-level "mcp" block. Each entry has a name you choose, a type (local or remote), and the command or URL to run it.
Local vs remote MCPs
Local MCPs
- Run as a process on your machine
- You install the server package (
uvx,npx,pip, or a custom script) - OpenCode spawns it at startup
- More control — works offline, no external dependency
- Requires the package installed locally
- Config uses a
"command"array pointing to the executable
Remote MCPs
- Hosted by the tool provider — you just point at their URL
- Nothing to install locally
- Auth via a token in a request header
- Dependent on the provider's availability and their MCP implementation
- Faster to get started
- Config uses a
"url"field instead of"command"
The {env:VARIABLE_NAME} pattern tells OpenCode to read the value from your environment at runtime — never put real tokens directly in this file. See Handling API Keys & Tokens Safely for how to set environment variables correctly.
Example MCPs to configure
A starting point — not exhaustive. For anything not listed here, just ask OpenCode: "Help me add [tool name] as an MCP in opencode.json" and it will walk you through it. The full registry is at github.com/modelcontextprotocol/servers.
| Tool | What it connects | Notes |
|---|---|---|
| Atlassian | Jira + Confluence — tickets, pages, comments | Add multiple entries for multiple instances. Needs uv installed. |
| Webex | Rooms, messages, meetings, people search | Requires OAuth tokens. Personal Access Tokens expire after 12 hours. |
| Airtable | Read and write records across any base | Official remote MCP — no install needed, just a Personal Access Token. |
| Outlook | Email, calendar, contacts via Microsoft Graph | Requires an Azure app registration to get credentials. |
| Chrome DevTools | Control a running Chrome browser — screenshots, audits, interaction | Runs via npx, no install. Chrome must be open on your machine. |
| Backlog.md | Local markdown-based task tracking | Tasks stored as files — no external service. Good for personal project tracking. |
| Circuit | An AI gateway with access to internal data sources and hosted LLMs | Organisation-internal setup required. Built by milugo — see their repo for setup steps. |
| GitHub | Repos, PRs, issues, code search | Official MCP. Runs via npx + a Personal Access Token. |
| Slack | Channels, messages, people search | Requires a Slack app with a Bot User OAuth Token. |
How to add a new MCP — step by step
- Find the package. Search the MCP servers registry or the tool's own documentation. Most tools now publish an official MCP server.
- Install it. Usually
uvx,npx, orpip. Many run vianpxwith no separate install step. - Get credentials. Generate an API token in the tool's developer settings. Start with minimal scopes.
- Store the credential safely. Add it as an environment variable in
~/.zshrc, thensource ~/.zshrc. See API Keys & Tokens. - Add the config block to
~/.config/opencode/opencode.jsonusing{env:MY_TOOL_TOKEN}— never paste the token directly. - Restart OpenCode. MCP connections are established at startup.
- Test with a read first. Confirm the connection works before trying any write actions.
Lessons learned
-
Never hardcode tokens in opencode.json.
If the file ever touches a git repo — even briefly — the token is compromised. Always use
{env:VARIABLE_NAME}so the file contains no secrets. -
Keep opencode.json out of version control.
Even if you think everything uses
{env:...}, one slip (a URL with an embedded key, a username in a header) is enough. Don't commit it. - Test read before write. Write MCPs take real actions — a sent Webex message is sent, a published Confluence page is live. Confirm the connection works with a read-only query first.
- Check token expiry when things break. Webex Personal Access Tokens expire after 12 hours, for example. An MCP that suddenly stops working is usually an expired token. Use OAuth refresh tokens for MCPs you rely on daily.
-
Disable MCPs you're not using.
Every enabled MCP adds startup time and consumes context. Set
"enabled": false— you can flip it back in seconds.