OpenCode MCP 설정 방법 (초간단) — 로컬/원격 MCP 서버 붙이는 법

 

OpenCode MCP 설정 방법 (초간단) — 로컬/원격 MCP 서버 붙이는 법

메타 설명(검색 노출용)
OpenCode에서 MCP(Model Context Protocol) 서버를 설정하면, 외부 도구를 에이전트(LLM)에 “툴”로 추가해 사용할 수 있어요. 이 글은 **opencode.json(c)에서 MCP를 켜는 방법(로컬/원격/OAuth)**을 아주 쉽게 정리합니다. (OpenCode)

---

MCP가 뭔데? (한 줄 요약)

MCP 서버를 추가하면, 그 서버가 제공하는 “툴”들이 OpenCode의 기본 툴과 함께 LLM에서 자동으로 사용 가능해집니다. (OpenCode)

⚠️ 주의: MCP 서버를 많이 켜면 컨텍스트(토큰)가 늘어나서 한도 초과가 날 수 있어요. 특히 일부 서버(예: GitHub 관련)는 토큰이 크게 늘 수 있다고 문서에서 경고합니다. (OpenCode)

---

1) MCP 서버 “켜기” (Enable) — 제일 기본 형태

opencode.jsonc(또는 opencode.json) 설정에서 mcp 아래에 서버를 이름(키)로 등록하고 enabled: true로 켭니다. (OpenCode)

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-mcp-server": {
      "enabled": true
    }
  }
}

• my-mcp-server ← 이 이름이 툴 이름의 접두사/서버 식별자가 됩니다. (OpenCode)
• 잠깐 꺼두고 싶으면 enabled: false로 바꾸면 됩니다. (OpenCode)

---

2) 로컬 MCP 서버 추가 (Local) — 내 PC에서 npx로 실행

로컬 MCP는 type: "local" + command로 실행 명령을 적습니다. (OpenCode)

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

✅ 실습용 추천 예시: server-everything 붙이기

문서 예시로 소개된 테스트 MCP 서버(@modelcontextprotocol/server-everything)를 바로 붙일 수 있어요. (OpenCode)

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

그리고 프롬프트에 이런 식으로 사용합니다(문서 예시). (OpenCode)

use the mcp_everything tool to add the number 3 and 4

---

3) 원격 MCP 서버 추가 (Remote) — URL로 붙이기

원격 MCP는 type: "remote" + url이 핵심입니다. 필요하면 headers로 API 키도 넣습니다. (OpenCode)

{
  "$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"
      }
    }
  }
}

---

4) OAuth 필요한 원격 MCP라면? (인증까지 초간단)

OpenCode는 원격 MCP에서 인증이 필요하면 401을 감지해서 OAuth 흐름을 자동으로 진행할 수 있다고 안내합니다. (OpenCode)

(1) 자동 OAuth (대부분 이걸로 충분)

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-oauth-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp"
    }
  }
}

(2) 수동으로 인증 트리거

처음 사용할 때 자동으로 뜨지 않으면 아래 명령으로 인증을 시작할 수 있어요. (OpenCode)

opencode mcp auth my-oauth-server

(3) MCP 목록/로그아웃

opencode mcp list
opencode mcp logout my-oauth-server

토큰은 ~/.local/share/opencode/mcp-auth.json에 저장된다고 문서에 나옵니다. (OpenCode)

(4) OAuth를 끄고 API 키 방식만 쓰고 싶다면

{
  "$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 자동 감지를 끄는 옵션도 문서에 안내돼 있습니다. (OpenCode)

---

5) MCP 툴 “관리” 꿀팁 — 전부 켜면 느려져요

MCP는 “툴”로 등록되기 때문에, 전역(Global)에서 끄거나 특정 에이전트에서만 켜는(Per agent) 방식이 가능합니다. (OpenCode)

전역에서 특정 MCP만 끄기(또는 glob 패턴으로 끄기)

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-mcp-foo": { "type": "local", "command": ["bun", "x", "my-mcp-command-foo"] },
    "my-mcp-bar": { "type": "local", "command": ["bun", "x", "my-mcp-command-bar"] }
  },
  "tools": {
    "my-mcp*": false
  }
}

glob 패턴(*, ?)으로 묶어서 끄는 예시가 문서에 있습니다. (OpenCode)

에이전트별로만 MCP 켜기(추천)

1. 전역에서 MCP 툴을 꺼두고
2. 특정 agent에서만 다시 true로 켜는 방식이에요. (OpenCode)

---

“가장 쉬운 시작 루트” 요약

1. opencode.jsonc 열기
2. 테스트용 mcp_everything 추가(로컬)
3. OpenCode 실행 후 프롬프트에 use the mcp_everything tool ...로 호출
4. MCP가 많아지면 glob로 끄거나 agent별로만 켜기(토큰/컨텍스트 관리) (OpenCode)

---

 

• OpenCode MCP 설정 방법: 로컬/원격 MCP 서버 추가하는 법(초보자용)
• 오픈코드 MCP 서버 붙이기: opencode.jsonc 설정 + OAuth 인증까지

 

• OpenCode MCP 설정
• 오픈코드 MCP 서버
• opencode.jsonc MCP
• MCP 로컬 서버 설정
• MCP 원격 서버 OAuth