MCP Tools

Kết nối OpenCode với 200+ MCP servers.

Tổng quan

Model Context Protocol (MCP) là một chuẩn mở cho phép kết nối các công cụ bên ngoài với AI. OpenCode hỗ trợ cả local và remote MCP servers.

Khi đã thêm, MCP tools tự động available cho LLM cùng với các built-in tools.

Lưu ý quan trọng

MCP servers thêm vào context, nên bạn cần cẩn thận chọn những server nào cần enable.

Một số MCP servers như GitHub MCP server có xu hướng thêm nhiều tokens và có thể dễ dàng vượt quá context limit.

Enable MCP Server

Định nghĩa MCP servers trong config opencode.json dưới key mcp:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-mcp-server": {
      "type": "local",
      "command": ["npx", "-y", "my-mcp-command"],
      "enabled": true
    }
  }
}

Disable server tạm thời bằng enabled: false.

Override remote defaults

Tổ chức có thể cung cấp MCP servers mặc định qua endpoint .well-known/opencode. Các servers này thường bị tắt mặc định (enabled: false) để user chủ động bật khi cần.

Để bật một server từ remote config, thêm vào local config với enabled: true:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": true
    }
  }
}

Local config sẽ ghi đè remote defaults. Xem thứ tự ưu tiên config để biết thêm chi tiết.

Local MCP Server

Thêm local MCP server với type: "local":

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-local-mcp": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"],
      "enabled": true,
      "environment": {
        "MY_API_KEY": "xxx"
      }
    }
  }
}

Options cho Local MCP

Ví dụ: MCP Everything

{
  "mcp": {
    "mcp_everything": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"]
    }
  }
}

Sử dụng trong prompt:

use the mcp_everything tool to add 3 and 4

Remote MCP Server

Thêm remote MCP server với type: "remote":

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-remote-mcp": {
      "type": "remote",
      "url": "https://my-mcp-server.com",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer MY_API_KEY"
      }
    }
  }
}

Options cho Remote MCP

OAuth Authentication

OpenCode tự động xử lý OAuth cho remote MCP servers. Khi server yêu cầu auth, OpenCode sẽ:

1. Detect 401 response và khởi động OAuth flow
2. Sử dụng Dynamic Client Registration (RFC 7591) nếu server hỗ trợ
3. Lưu tokens an toàn cho các requests sau

Cấu hình OAuth tự động

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

Với Client Credentials

{
  "mcp": {
    "my-oauth-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "clientId": "{env:MY_MCP_CLIENT_ID}",
        "clientSecret": "{env:MY_MCP_CLIENT_SECRET}",
        "scope": "tools:read tools:execute"
      }
    }
  }
}

Với Client Credentials (Pre-registered)

Nếu bạn có client credentials từ MCP server provider, cấu hình:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-oauth-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "clientId": "{env:MY_MCP_CLIENT_ID}",
        "clientSecret": "{env:MY_MCP_CLIENT_SECRET}",
        "scope": "tools:read tools:execute"
      }
    }
  }
}

Authenticating

Bạn có thể kích hoạt xác thực thủ công hoặc quản lý credentials.

Authenticate với một MCP server cụ thể:

opencode mcp auth my-oauth-server

Liệt kê tất cả servers và trạng thái auth:

opencode mcp list

Xóa credentials đã lưu:

opencode mcp logout my-oauth-server

Lệnh mcp auth sẽ mở browser để bạn authorize. Sau khi authorize, OpenCode lưu tokens an toàn trong ~/.local/share/opencode/mcp-auth.json.

Disabling OAuth

Nếu bạn muốn tắt OAuth tự động cho một server (ví dụ server dùng API keys thay vì OAuth), đặt oauth thành false:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-api-key-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "oauth": false,
      "headers": {
        "Authorization": "Bearer {env:MY_API_KEY}"
      }
    }
  }
}

OAuth Options

Debugging

Nếu remote MCP server không authenticate được, dùng các lệnh sau để debug:

# Xem auth status cho tất cả OAuth-capable servers
opencode mcp auth list

# Debug connection và OAuth flow cho một server cụ thể
opencode mcp debug my-oauth-server

Lệnh mcp debug hiển thị auth status hiện tại, test HTTP connectivity, và thử OAuth discovery flow.

Quản lý MCPs

Global - Enable/Disable tất cả

{
  "mcp": {
    "my-mcp-foo": { "type": "local", "command": ["..."] },
    "my-mcp-bar": { "type": "local", "command": ["..."] }
  },
  "tools": {
    "my-mcp-foo": false,
    "my-mcp*": false
  }
}

Per Agent

Chỉ enable MCP cho agent cụ thể:

{
  "mcp": {
    "my-mcp": {
      "type": "local",
      "command": ["bun", "x", "my-mcp-command"],
      "enabled": true
    }
  },
  "tools": {
    "my-mcp*": false
  },
  "agent": {
    "my-agent": {
      "tools": {
        "my-mcp*": true
      }
    }
  }
}

Glob patterns

Khi dùng wildcards để match MCP tools, lưu ý:

• * khớp với zero hoặc nhiều ký tự (ví dụ "my-mcp*" khớp my-mcp_search, my-mcp_list, v.v.)
• ? khớp với đúng một ký tự
• Các ký tự khác khớp chính xác

:::note MCP server tools được đăng ký với server name làm prefix. Để tắt tất cả tools của một server, dùng:

"mymcpservername_*": false

:::

Ví dụ thực tế

Context7 - Search Docs

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

Sử dụng:

Configure Cloudflare Worker script to cache JSON API responses. use context7

Grep by Vercel - Search GitHub Code

{
  "mcp": {
    "gh_grep": {
      "type": "remote",
      "url": "https://mcp.grep.app"
    }
  }
}

Sử dụng:

How to set a custom domain in SST Astro component? use the gh_grep tool

Sentry - Error Tracking

{
  "mcp": {
    "sentry": {
      "type": "remote",
      "url": "https://mcp.sentry.dev/mcp",
      "oauth": {}
    }
  }
}

Authenticate:

opencode mcp auth sentry

Sử dụng:

Show me the latest unresolved issues in my project. use sentry

Tips & Best Practices

1. Giới hạn số MCP servers

Mỗi MCP server thêm tools vào context. Chỉ enable những gì thực sự cần.

2. Sử dụng per-agent config

Chỉ enable MCP cho agents cần sử dụng thay vì enable globally.

3. Thêm vào AGENTS.md

Thêm hướng dẫn vào AGENTS.md để agent biết khi nào dùng MCP:

When you need to search docs, use `context7` tools.
If unsure how to do something, use `gh_grep` to search GitHub examples.

4. Kiểm tra timeout

Nếu MCP server chậm, tăng timeout:

{
  "mcp": {
    "slow-server": {
      "type": "remote",
      "url": "https://slow-mcp.example.com",
      "timeout": 30000
    }
  }
}

Tham khảo

• Docs chính thức: MCP servers
• Model Context Protocol
• MCP Servers Registry