DEV Community

Nirvan Jha
Nirvan Jha

Posted on

Give Your Terminal Agent Superpowers: Setting Up opencode with MCP Connections (Step by Step)

#ai #mcp #opencode #tutorial

Last week I typed this into my terminal:

"Add my dev.to account and write a blog post about our project."

And it actually happened. No browser, no copy-pasting, no context switching. My coding agent just... did it.

This post breaks down exactly how to set up opencode (an open-source AI coding agent that lives in your terminal) and wire it up to MCP connections so it can talk to your personal tools — GitHub, Gmail, Notion, dev.to, even X/Twitter. This is the exact setup I use, simplified into copy-paste steps.

First, two quick concepts (30 seconds each)

opencode is an AI agent for your terminal. It reads your codebase, edits files, runs commands, and builds features with you. Think Claude Code / Cursor, but open source and provider-agnostic (use any model you want).

MCP (Model Context Protocol) is a standard plug format for AI tools. An MCP server exposes tools (like "send an email" or "create an issue") in a way any MCP client can use. Once you add an MCP server to opencode, its tools appear alongside built-in ones automatically.

The mental model:

opencode (the agent)
 ├── built-in tools: read files, edit, bash...
 └── MCP servers (plugs)
      ├── github-mcp     → create PRs, read issues
      ├── sentry-mcp     → check error logs
      └── composio-mcp   → 500+ apps: Gmail, Notion, dev.to, X...
Enter fullscreen mode Exit fullscreen mode

One config file controls all of it. Let's build it.

Part 1 — Install opencode (5 minutes)

Pick one:

# macOS / Linux
curl -fsSL https://opencode.ai/install | bash

# npm (works on Windows too)
npm i -g opencode-ai@latest

# macOS with Homebrew
brew install sst/tap/opencode
Enter fullscreen mode Exit fullscreen mode

Then connect an AI model provider:

opencode auth login
Enter fullscreen mode Exit fullscreen mode

Pick your provider (Anthropic, OpenAI, Google, or 75+ others), paste your API key, done.

Run opencode inside any project folder and you're live. That's the whole "install" story.

Part 2 — Add your first MCP server (10 minutes)

All configuration lives in opencode.json at your project root (or globally at ~/.config/opencode/opencode.json if you want it everywhere).

Option A: A remote MCP server

Remote = the tools run on someone else's server; opencode talks to it over HTTP.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Restart opencode, then try:

Configure a Cloudflare Worker to cache JSON responses. use context7
Enter fullscreen mode Exit fullscreen mode

Naming matters: saying "use context7" in your prompt nudges the agent toward those specific tools.

Option B: A local MCP server

Local = opencode spawns the process on your machine. Great for anything self-hosted or privacy-sensitive.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "everything": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

If the server needs login: OAuth is handled for you

For remote servers that need auth (like Sentry), opencode detects the 401 and opens your browser to authenticate automatically. You can also trigger it manually:

opencode mcp auth sentry   # opens browser OAuth flow
opencode mcp list          # see all servers + auth status
Enter fullscreen mode Exit fullscreen mode

Tokens are stored securely in ~/.local/share/opencode/mcp-auth.json. For plain API-key servers, skip OAuth and pass headers instead:

{
  "mcp": {
    "my-server": {
      "type": "remote",
      "url": "https://my-server.com/mcp",
      "oauth": false,
      "headers": { "Authorization": "Bearer {env:MY_API_KEY}" }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Part 3 — The Composio route: one MCP, hundreds of personal apps

Here's the trick I actually use daily. Instead of configuring a separate MCP server for every app, I connect Composio once — it's a managed layer with pre-built integrations for 500+ apps (GitHub, Gmail, Slack, Notion, Linear, dev.to, X/Twitter...).

Why this is worth it:

  • Auth is managed for you. No wrangling OAuth callbacks or API keys per app.
  • Tools are curated. Instead of dumping 200 raw endpoints into your context, you get clean, high-level actions.
  • Connections persist. Connect your account once; every agent session reuses it.

Step-by-step setup

Step 1 — Create a free Composio account at dashboard.composio.dev and grab your API key.

Step 2 — Add Composio's MCP endpoint to opencode following their connect guide:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "composio": {
      "type": "remote",
      "url": "https://mcp.composio.dev/your-composio-endpoint",
      "headers": {
        "Authorization": "Bearer {env:COMPOSIO_API_KEY}"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

(Composio's dashboard shows your exact personal URL — copy it from there.)

Step 3 — Connect an app. Inside opencode, just ask:

Search composio tools for dev.to, and connect my dev.to account
Enter fullscreen mode Exit fullscreen mode

The agent finds the right toolkit, generates a secure auth link, you click it, paste your dev.to API key (from dev.to/settings/extensions), and the connection flips to Active. Same flow works for Google, Notion, Slack — whatever uses OAuth, you just click "Allow".

Step 4 — Use it.

List my unpublished drafts on dev.to using composio
Enter fullscreen mode Exit fullscreen mode

Real-world gotcha: X/Twitter costs money now

When I tried connecting X, I learned the hard way: since February 2026 the X API has no free tier. New developers are on pay-per-use credits (~$0.015 per tweet, $0.20 if it contains a link), and X requires you to preload credits into developer.x.com before any call succeeds. Composio also doesn't manage X auth for you — you must register your own X app credentials.

Lesson: check each platform's API pricing before promising your agent will post to it. Most others (dev.to, GitHub, Notion, Gmail) are free.

Part 4 — Test the whole chain end-to-end

A good smoke test after wiring everything up:

Use composio to:
1. Verify which accounts are connected
2. Create a draft post on dev.to titled "Hello from my terminal"
   with a short body
Enter fullscreen mode Exit fullscreen mode

If both steps work, you're fully wired: model → opencode → MCP → Composio → real-world action.

Part 5 — Bonus level: teach it your rules with skills

MCP gives your agent new hands; skills give it taste. Drop a markdown file into .opencode/skills/<name>/SKILL.md describing a specialty, and register it in your config:

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    ".opencode/skills/frontend-creativity-playbook/SKILL.md"
  ]
}
Enter fullscreen mode Exit fullscreen mode

Mine contains a frontend design playbook — typography scales, color systems, motion principles. Now every time I build UI, the agent already knows my standards. It's like onboarding a junior dev who never forgets anything.

Tips that saved me time

  1. Context is finite. Every MCP tool description gets injected into the model's context. Five lean servers > twenty bloated ones. The GitHub MCP alone can eat a huge chunk.
  2. Disable without deleting. "tools": { "composio*": false } turns off matching tools temporarily.
  3. Gate risky tools per-agent. Disable globally, then re-enable only inside an agent that needs them — nice pattern for posting/publishing tools you don't want firing mid-refactor.
  4. Debug auth fast: opencode mcp debug <server-name> shows auth status and tests connectivity.
  5. Prefer managed-auth toolkits (most of Composio's catalog) over bring-your-own-key ones when starting out — fewer moving parts.

Wrapping up

The barrier between "AI that writes code" and "AI that operates my workspace" turned out to be one JSON file. Setup order that worked for me:

  1. Install opencode → opencode auth login
  2. Add one small remote MCP (Context7 is harmless and useful)
  3. Add Composio → connect 2–3 apps you actually use
  4. Add a skill file for your domain conventions
  5. Keep the tool count lean

Start with one app. When your agent publishes its first draft post while you're still in the terminal, you'll get it.

What would you connect first? Drop a comment — and yes, this post was drafted by my terminal agent.

Top comments (0)