Skip to content

MCP Servers

Jump to bottom
Fisherk2 edited this page Jul 10, 2026 · 3 revisions

MCP Servers

MCP (Model Context Protocol) servers extend OpenCode agents with external tools and data sources. This page covers the MCP servers that come pre-configured in this workspace template, how to activate them, and which template features depend on them.

Official documentation: opencode.ai/docs/mcp-servers/ covers the basics of local, remote, and OAuth-based MCP server configuration.

Find MCP servers: mcp.so | glama.ai/mcp/servers

Pre-Configured MCP Servers

The template ships with 4 MCP servers pre-configured in opencode.json. Only context7 is enabled by default; the rest are disabled to conserve context and must be activated on demand.

Server Type Default Template Feature
context7 Remote ✅ Enabled Documentation queries (find-docs skill)
chrome-devtools Local ❌ Disabled /webperf Deep mode, browser debugging
excel Local ❌ Disabled Spreadsheet manipulation (xlsx skill)
jupyter Local ❌ Disabled AI-powered notebook automation

Context Consumption Warning

MCP servers add tokens to every conversation turn. The more servers and tools you enable, the faster you'll reach the context limit.

Rule of thumb: Enable only what you need for your current task. Disable servers globally and activate them per-agent when possible (see Per-Agent Control below).

Activating MCP Servers

Each server requires different prerequisites. Follow the steps below for the server you need.

Context7 — Documentation Search

Remote MCP server that provides up-to-date library documentation. Used by the find-docs skill.

Pre-configured as: "enabled": true — no setup needed.

{
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "enabled": true
    }
  }
}

For higher rate limits, sign up for a free account and set your API key:

{
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}"
      }
    }
  }
}

Usage: Agents automatically use context7 when querying library documentation. You can also invoke it manually with use context7 in your prompt.

Chrome DevTools MCP — Web Performance & Debugging

Local MCP server from the Chrome DevTools team (ChromeDevTools/chrome-devtools-mcp) that gives AI agents control over a live Chrome browser. Provides Lighthouse audits, performance traces, Core Web Vitals measurement, console inspection, and screenshots.

Required for /webperf Deep mode — without this MCP, web-performance-auditor operates in Quick mode (static source analysis only, metrics marked as "not measured").

Prerequisites

  • Node.js LTS (already present in this workspace)
  • Google Chrome (stable or newer)
  • No additional dependencies — runs via npx

Quick Start

  1. Open Chrome with remote debugging:

    google-chrome --remote-debugging-port=9222

    Or use --auto-connect (Chrome 144+):

    npx -y chrome-devtools-mcp@latest --auto-connect

  2. Enable the MCP server in opencode.json:

    {
  "mcp": {
    "chrome-devtools": {
      "type": "local",
      "command": ["npx", "-y", "chrome-devtools-mcp@latest"],
      "enabled": true
    }
  }
}

  3. Restart OpenCode for the change to take effect.

Available Tools

Tool Purpose
lighthouse_audit Run Lighthouse and get performance score + diagnostics
performance_start_trace Start recording a performance trace
performance_stop_trace Stop trace and get analysis
performance_analyze_insight Analyze performance data for bottlenecks
screenshot Capture page screenshot
console_logs Get browser console output
page_capture Capture page state for inspection

Usage Examples

"Run a Lighthouse audit on localhost:3000 and tell me what's hurting the performance score."

"Record a performance trace of the page load and identify long tasks blocking INP."

"Check the console for errors on the current page."

Excel MCP Server — Spreadsheet Manipulation

Local MCP server for reading, writing, and manipulating Excel files (.xlsx) directly from OpenCode agents. Supports workbooks, worksheets, ranges, formulas, charts, pivot tables, formatting, and more. Used by the xlsx skill.

Prerequisites

  • Python 3 with uv installed (pip install uv or brew install uv)
  • No additional npm dependencies

Quick Start

  1. Verify the dependency runs correctly:

    uvx excel-mcp-server stdio

    If this is your first run, uv will download and cache the server automatically.

  2. Enable the MCP server in opencode.json:

    {
  "mcp": {
    "excel": {
      "type": "local",
      "command": ["uvx", "excel-mcp-server", "stdio"],
      "enabled": true
    }
  }
}

  3. Restart OpenCode for the change to take effect.

Repository: github.com/haris-musa/excel-mcp-server

Jupyter Notebook — AI-Powered Notebook Automation

Local MCP server that gives AI agents full control over a live Jupyter notebook session — run code, add markdown, manage packages, inspect variables, and more.

Prerequisites

  • Python 3 with uv installed
  • Docker (recommended for the Jupyter server) or Python packages (jupyterlab, ipykernel)

Quick Start

1. Start a Jupyter server

Pick one method:

# A) With Docker (recommended — includes jupyter-collaboration)
git clone https://github.com/Cyb3rWard0g/agent-jupyter-toolkit.git
cd agent-jupyter-toolkit/packages/mcp-jupyter-notebook/quickstarts
docker compose up -d --build

# B) Or locally
pip install jupyterlab ipykernel jupyter-collaboration
jupyter lab --port 8888 --IdentityProvider.token=mcp-dev-token

2. Enable the MCP server in opencode.json:

{
  "mcp": {
    "jupyter": {
      "type": "local",
      "command": ["uvx", "mcp-jupyter-notebook"],
      "enabled": true,
      "env": {
        "MCP_JUPYTER_SESSION_MODE": "server",
        "MCP_JUPYTER_BASE_URL": "http://localhost:8888",
        "MCP_JUPYTER_TOKEN": "mcp-dev-token",
        "MCP_JUPYTER_NOTEBOOK_PATH": "agent_demo.ipynb"
      }
    }
  }
}

3. Restart OpenCode — the server will connect automatically.

Local Mode (no Jupyter server needed)

For lightweight sessions without a full Jupyter server:

{
  "mcp": {
    "jupyter": {
      "type": "local",
      "command": ["uvx", "mcp-jupyter-notebook", "--mode", "local"],
      "enabled": false
    }
  }
}

Note: Local mode runs a kernel directly. No MCP_JUPYTER_BASE_URL or MCP_JUPYTER_TOKEN required.

Environment Variables

Variable CLI Flag Description Default
MCP_JUPYTER_SESSION_MODE --mode server (remote Jupyter) or local server
MCP_JUPYTER_BASE_URL --base-url Jupyter server URL (required in server mode) —
MCP_JUPYTER_TOKEN --token Jupyter API token —
MCP_JUPYTER_KERNEL_NAME --kernel-name Kernel spec name python3
MCP_JUPYTER_NOTEBOOK_PATH --notebook-path Notebook file path (.ipynb) auto-generated
MCP_JUPYTER_LOG_LEVEL — DEBUG, INFO, WARNING, ERROR INFO

Repository: github.com/Cyb3rWard0g/agent-jupyter-toolkit

Full tool reference: packages/mcp-jupyter-notebook/docs/tools.md

Per-Agent Control

The template recommends a disable-globally, enable-per-agent strategy to conserve context while giving specific agents access to the tools they need.

For example, chrome-devtools is useful for agents that run browser tests or performance audits, but unnecessary for other agents. Here's how to disable it globally and enable it only for mictlantecuhtli and tlaloc:

{
  "mcp": {
    "chrome-devtools": {
      "type": "local",
      "command": ["npx", "-y", "chrome-devtools-mcp@latest"],
      "enabled": true
    }
  },
  "tools": {
    "chrome-devtools*": false
  },
  "agent": {
    "mictlantecuhtli": {
      "tools": {
        "chrome-devtools*": true
      }
    },
    "tlaloc": {
      "tools": {
        "chrome-devtools*": true
      }
    }
  }
}

This pattern applies to any MCP server:

  1. Enable the server in the mcp section (so OpenCode starts it)
  2. Disable all its tools globally in the tools section
  3. Re-enable tools only for specific agents using agent.<name>.tools

Official docs: See opencode.ai/docs/mcp-servers#per-agent for more on per-agent tool control.

Adding New MCP Servers

Beyond the pre-configured servers, you can add any MCP server available in the ecosystem. Follow the basic pattern from the official OpenCode docs:

Local MCP server:

{
  "mcp": {
    "my-server": {
      "type": "local",
      "command": ["npx", "-y", "my-mcp-package"],
      "enabled": true
    }
  }
}

Remote MCP server:

{
  "mcp": {
    "my-server": {
      "type": "remote",
      "url": "https://my-mcp-server.com/mcp",
      "enabled": true
    }
  }
}

Useful Servers to Consider

Server Description Package / URL
Filesystem File system access @modelcontextprotocol/server-filesystem
PostgreSQL Database access @modelcontextprotocol/server-postgres
Puppeteer Browser automation @modelcontextprotocol/server-puppeteer
Memory Persistent storage @modelcontextprotocol/server-memory
Sentry Error tracking (remote) https://mcp.sentry.dev/mcp (+ OAuth)
Grep by Vercel GitHub code search (remote) https://mcp.grep.app

Avoid the GitHub MCP server: It consumes a large number of tokens. Use the gh CLI via the bash tool instead.

Which Template Features Need Which MCP

Feature MCP Required Without MCP
Documentation queries (find-docs skill) context7 Falls back to training data
/webperf Deep mode chrome-devtools Quick mode (static analysis only)
Browser testing (browser-testing-with-devtools skill) chrome-devtools No runtime browser verification
Spreadsheet manipulation (xlsx skill) excel Manual CSV editing
Jupyter notebook automation jupyter Not available

Best Practices

  1. Enable only what you need — Each active MCP server adds tokens to every conversation. Disable servers you're not actively using.
  2. Prefer per-agent activation — Disable tools globally and enable them only for specific agents that need them (see Per-Agent Control).
  3. Use @latest for Chrome DevTools MCP — chrome-devtools-mcp@latest ensures you always get the newest version without manual updates.
  4. Use environment variables for secrets — Reference API keys and tokens with {env:VAR_NAME} in the config. Never hardcode credentials.
  5. Configure timeouts for slow servers — If an MCP server is slow to respond, increase the timeout value (default: 5000ms).
  6. Test new servers incrementally — Add one server at a time and verify it works before adding the next. This helps isolate configuration issues.
  7. Run opencode mcp list to see all configured servers and their authentication status.

See Also

Clone this wiki locally