MCP 서버

Model Context Protocol 또는 MCP를 사용하여 OpenCode에 외부 도구를 추가할 수 있습니다. OpenCode는 로컬 및 원격 서버를 모두 지원합니다.

추가되면 MCP 도구는 기본 제공 도구와 함께 LLM에서 자동으로 사용할 수 있습니다.

주의사항

MCP 서버를 사용하면 컨텍스트에 추가됩니다. 많은 도구가 있으면 빠르게 누적될 수 있습니다. 따라서 어떤 MCP 서버를 사용하는지 주의하는 것이 좋습니다.

활성화

OpenCode 구성의 mcp 아래에 MCP 서버를 정의할 수 있습니다. 각 MCP를 고유한 이름으로 추가합니다. LLM에 프롬프트할 때 해당 이름으로 MCP를 참조할 수 있습니다.

opencode.jsonc

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

enabled를 false로 설정하여 서버를 비활성화할 수도 있습니다. 이는 일시적으로 서버를 제거하지 않고 비활성화하려는 경우에 유용합니다.

원격 기본값 재정의

조직은 .well-known/opencode 엔드포인트를 통해 기본 MCP 서버를 제공할 수 있습니다. 이러한 서버는 기본적으로 비활성화되어 사용자가 필요한 것을 선택할 수 있습니다.

조직의 원격 구성에서 특정 서버를 활성화하려면 enabled: true로 로컬 구성에 추가합니다:

opencode.json

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

로컬 구성 값이 원격 기본값을 재정의합니다. 자세한 내용은 구성 우선순위를 참조하세요.

로컬

type을 "local"로 설정하여 로컬 MCP 서버를 추가합니다.

opencode.jsonc

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

명령은 로컬 MCP 서버를 시작하는 방법입니다. 환경 변수의 목록도 전달할 수 있습니다.

예를 들어, 테스트 @modelcontextprotocol/server-everything MCP 서버를 추가하는 방법은 다음과 같습니다.

opencode.jsonc

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

사용하려면 프롬프트에 use the mcp_everything tool을 추가할 수 있습니다.

use the mcp_everything tool to add the number 3 and 4

옵션

로컬 MCP 서버를 구성하기 위한 모든 옵션은 다음과 같습니다.

옵션	타입	필수	설명
`type`	String	Y	MCP 서버 연결 타입, `"local"`이어야 합니다.
`command`	Array	Y	MCP 서버를 실행하는 명령 및 인수.
`environment`	Object		서버 실행 시 설정할 환경 변수.
`enabled`	Boolean		시작 시 MCP 서버 활성화 또는 비활성화.
`timeout`	Number		MCP 서버에서 도구 가져오기의 시간 제한(ms). 기본값 5000 (5초).

원격

type을 "remote"로 설정하여 원격 MCP 서버를 추가합니다.

opencode.json

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

url은 원격 MCP 서버의 URL이며 headers 옵션으로 헤더 목록을 전달할 수 있습니다.

옵션

옵션	타입	필수	설명
`type`	String	Y	MCP 서버 연결 타입, `"remote"`이어야 합니다.
`url`	String	Y	원격 MCP 서버의 URL.
`enabled`	Boolean		시작 시 MCP 서버 활성화 또는 비활성화.
`headers`	Object		요청과 함께 보낼 헤더.
`oauth`	Object		OAuth 인증 구성. 아래 OAuth 섹션을 참조하세요.
`timeout`	Number		MCP 서버에서 도구 가져오기의 시간 제한(ms). 기본값 5000 (5초).

OAuth

OpenCode는 원격 MCP 서버에 대한 OAuth 인증을 자동으로 처리합니다. 서버가 인증을 요구하면 OpenCode는:

401 응답을 감지하고 OAuth 흐름 시작
서버가 지원하면 Dynamic Client Registration (RFC 7591) 사용
이후 요청을 위해 토큰을 안전하게 저장

자동

대부분의 OAuth 지원 MCP 서버에는 특수 구성이 필요하지 않습니다. 원격 서버만 구성하세요:

opencode.json

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

서버가 인증을 요구하면 처음 사용할 때 인증하라는 메시지가 표시됩니다. 그렇지 않으면 수동으로 흐름 트리거할 수 있습니다 opencode mcp auth <server-name>.

사전 등록

MCP 서버 provider의 클라이언트 자격 증명이 있으면 구성할 수 있습니다:

opencode.json

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

인증

인증하거나 자격 증명을 관리할 수 있습니다.

특정 MCP 서버로 인증:

opencode mcp auth my-oauth-server

모든 MCP 서버 및 인증 상태 나열:

opencode mcp list

저장된 자격 증명 제거:

opencode mcp logout my-oauth-server

mcp auth 명령은 브라우저에서 인가를 열 것입니다. 인가 후 OpenCode는 토큰을 ~/.local/share/opencode/mcp-auth.json에 안전하게 저장합니다.

OAuth 비활성화

API 키 대신 서버에 사용되는 서버에 자동 OAuth를 비활성화하려면 (예: oauth를 false로 설정):

opencode.json

{
  "$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 옵션

옵션	타입	설명
`oauth`	Object \| false	OAuth 구성 객체, 또는 자동 OAuth 감지를 비활성화하려면 `false`.
`clientId`	String	OAuth 클라이언트 ID. 제공되지 않으면 동적 클라이언트 등록이 시도됩니다.
`clientSecret`	String	인가 서버에서 요구하는 경우 OAuth 클라이언트 비밀.
`scope`	String	인가 중 요청할 OAuth 범위.

디버깅

원격 MCP 서버가 인증에 실패하면 다음으로 문제를 진단할 수 있습니다:

# 모든 OAuth 지원 서버의 인증 상태 보기
opencode mcp auth list
# 특정 서버의 연결 및 OAuth 흐름 디버그
opencode mcp debug my-oauth-server

mcp debug 명령은 현재 인증 상태를 보여주고 HTTP 연결을 테스트하며 OAuth 검색 흐름을 시도합니다.

관리

MCP는 OpenCode의 도구로 관리되므로 다른 도구와 마찬가지로 OpenCode 구성을 통해 관리할 수 있습니다.

전역

MCP를 전역에서 활성화 또는 비활성화할 수 있습니다.

opencode.json

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

glob 패턴을 사용하여 일치하는 모든 MCP를 비활성화할 수도 있습니다.

opencode.json

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

여기서 my-mcp* glob 패턴을 사용하여 모든 MCP를 비활성화합니다.

에이전트별

많은 MCP 서버가 있는 경우 에이전트별로만 활성화하고 전역에서 비활성화할 수 있습니다. 이렇게 하려면:

도구로 전역에서 비활성화합니다.
에이전트 구성에서 도구로 MCP 서버를 활성화합니다.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "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 패턴

glob 패턴은 간단한 regex globbing 패턴을 사용합니다:

*는 0개 이상의 임의 문자 일치 (예: "my-mcp*"는 my-mcp_search, my-mcp_list 등 일치)
?는 정확히 한 문자 일치
다른 모든 문자는 리터럴로 일치

예시

다음은 일반적인 MCP 서버의 예시입니다. 다른 서버를 문서화하려면 PR을 제출하세요.

Sentry

Sentry MCP 서버를 추가하여 Sentry 프로젝트 및 이슈와 상호작용합니다.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "sentry": {
      "type": "remote",
      "url": "https://mcp.sentry.dev/mcp",
      "oauth": {}
    }
  }
}

구성 추가 후 Sentry로 인증:

opencode mcp auth sentry

이것은 OAuth 흐름을 완료하고 OpenCode를 Sentry 계정에 연결하기 위한 브라우저 창을 엽니다.

인증되면 프롬프트에서 Sentry 도구를 사용하여 이슈, 프로젝트 및 오류 데이터를 쿼리할 수 있습니다.

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

Context7

Context7 MCP 서버를 추가하여 문서를 검색합니다.

opencode.json

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

무료 계정에 가입하면 API 키를 사용하고 더 높은 rate-limit을 얻을 수 있습니다.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}"
      }
    }
  }
}

여기서 CONTEXT7_API_KEY 환경 변수가 설정되어 있다고 가정합니다.

프롬프트에 use context7을 추가하여 Context7 MCP 서버를 사용합니다.

Configure a Cloudflare Worker script to cache JSON API responses for five minutes. use context7

또는 AGENTS.md에 다음과 같은 것을 추가할 수 있습니다.

문서를 검색해야 할 때 `context7` 도구를 사용하세요.

Grep by Vercel

Grep by Vercel MCP 서버를 추가하여 GitHub의 코드 스니펫을 검색합니다.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "gh_grep": {
      "type": "remote",
      "url": "https://mcp.grep.app"
    }
  }
}

MCP 서버를 gh_grep로 이름 지었으므로 에이전트가 사용하도록 프롬프트에 use the gh_grep tool을 추가할 수 있습니다.

What's the right way to set a custom domain in an SST Astro component? use the gh_grep tool

또는 AGENTS.md에 다음과 같은 것을 추가할 수 있습니다.

무언가를 어떻게 하는지 확실하지 않으면 `gh_grep`를 사용하여 GitHub의 코드 예제를 검색하세요.