OpenCode MCP 설정: 로컬·원격 서버를 연결하는 7단계

이 가이드는 MCP 도구 추가, 인증, 검증, 범위 제한과 문제 해결이라는 독립 검색 의도를 다룹니다. 일반 설치, Ollama, 세션 저장소는 기존 페이지에 남겨 키워드 충돌을 피합니다.

예시는 현재 공식 schema와 CLI를 따릅니다. 다만 제공자는 URL, 패키지, scope, 인증 방식을 바꿀 수 있으므로 팀에 적용하기 전 반드시 서버 소유자의 공식 문서를 확인하고 출처가 불명확한 명령을 민감한 저장소에서 실행하지 마세요.

로컬 서버는 OpenCode가 시작하는 자식 프로세스입니다. 신뢰할 수 있는 CLI 패키지나 로컬 파일 접근이 필요한 도구에 적합합니다. runtime, 패키지 관리자, 작업 폴더, 환경 변수와 OS 권한이 안정성을 결정합니다.

원격 서버는 HTTP 엔드포인트입니다. 문서 검색, 모니터링, 공유 데이터베이스에는 편하지만 네트워크와 인증 의존성이 생깁니다. 선호가 아니라 제공자가 공식 지원하는 전송 방식을 선택하세요.

OpenCode는 여러 설정 소스를 병합합니다. 여러 프로젝트에서 쓰는 도구는 전역 설정, 저장소 전용 도구는 opencode.json에 둡니다. 비밀 값은 환경 변수나 OAuth로 전달하고 Git에는 넣지 않습니다.

서버 이름은 안정적이고 설명적으로 만드세요. prompt, tool prefix, Agent 규칙에서 이 이름을 사용합니다. 선택 서버는 enabled: false로 문서화하면서 매 세션 로딩은 피할 수 있습니다.

로컬 항목에는 type: "local"과 command 배열이 필요합니다. 게시자와 소스를 확인하고 안정성이 중요하면 버전을 고정하며 민감 정보가 없는 폴더에서 먼저 테스트합니다.

token은 environment와 환경 변수 치환으로 전달합니다. 읽기 전용 개발 계정부터 시작하세요. 모델이 조심스럽더라도 도구는 token에 부여된 권한을 그대로 갖습니다.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "docs_search": {
      "type": "local",
      "command": ["npx", "-y", "trusted-mcp-package"],
      "enabled": true,
      "environment": { "MCP_TOKEN": "{env:MCP_TOKEN}" }
    }
  }
}

자리표시자 패키지는 서버 소유자의 공식 명령으로만 교체하세요.

원격 항목에는 type: "remote"와 HTTPS URL이 필요합니다. headers는 제공자 지침이 있을 때만 사용합니다. OAuth는 자동으로 시작하거나 opencode mcp auth <server-name>로 명시적으로 시작할 수 있습니다.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "monitoring": {
      "type": "remote",
      "url": "https://provider.example/mcp",
      "oauth": {}
    }
  }
}

먼저 opencode mcp list로 상태를 확인하고 연결이나 OAuth 문제는 opencode mcp debug <server-name>로 진단합니다. 이후 읽기 전용 질의를 실행하고 원본 시스템 결과와 비교합니다.

서버 이름, 패키지 또는 URL, runtime, 인증, prefix, 테스트 prompt, timeout, rollback을 기록하세요. 개인 실험을 다른 개발자가 재현할 수 있는 설정으로 바꿔 줍니다.

1. 제공자 확인공식 package, endpoint, 인증 사용.
2. 범위 선택전역, 프로젝트 또는 전문 Agent.
3. 한 항목 추가새 server는 한 번에 하나만.
4. 비밀 보호환경 변수나 OAuth, Git 금지.
5. 목록과 debug상태, 연결, OAuth 확인.
6. 읽기 테스트원본 시스템 결과와 비교.
7. 쓰기 허용log, diff, rollback 검증 후.

opencode mcp list
opencode mcp auth <server-name>
opencode mcp debug <server-name>
opencode mcp logout <server-name>

도구 설명은 컨텍스트를 소비합니다. 범위가 넓은 서버를 끄고 전문 Agent에서만 활성화하세요. 도입 전후 답변 품질과 token 사용량을 비교합니다.

로그나 인증 정보를 공유하기 전에 OpenCode 세션 저장소와 개인정보 가이드 를 확인하고 작은 컨텍스트의 로컬 모델과 MCP를 함께 쓴다면 OpenCode Ollama 가이드 도 읽으세요.

문제는 프로세스 또는 endpoint, 인증, OpenCode discovery, 마지막으로 prompt나 policy 순서로 나눕니다. 여러 층을 동시에 바꾸면 원인과 rollback이 불명확해집니다.

Figma나 Supabase는 제공자의 공식 설치 안내를 먼저 따르고 이 공통 검증 절차를 적용하세요. 일반 JSON은 프로젝트, region, 권한 차이를 놓칠 수 있습니다.

설치 기본은 OpenCode 배포 가이드. 로 돌아가고 공식 우선순위와 MCP 옵션은 아래 출처를 확인하세요.