512 lines
14 KiB
Plaintext
512 lines
14 KiB
Plaintext
---
|
|
title: MCP servers
|
|
description: Add local and remote MCP tools.
|
|
---
|
|
|
|
Model Context Protocol , 또는 MCP를 사용하여 OpenCode에 외부 도구를 추가할 수 있습니다. OpenCode는 로컬 및 원격 서버를 모두 지원합니다.
|
|
|
|
추가되면 MCP 도구는 내장 도구와 함께 LLM에 자동으로 사용할 수 있습니다.
|
|
|
|
---
|
|
|
|
#### 동굴
|
|
|
|
MCP 서버를 사용할 때 상황에 추가합니다. 도구가 많이 있으면 신속하게 추가 할 수 있습니다. 그래서 우리는 당신이 사용하는 MCP 서버와 주의를 기울여야 합니다.
|
|
|
|
:::tip
|
|
MCP 서버는 귀하의 컨텍스트에 추가하므로, 활성화할 수 있는 것을 주의해야 합니다.
|
|
:::
|
|
|
|
GitHub MCP 서버와 같은 특정 MCP 서버는 많은 토큰을 추가하고 컨텍스트 제한을 쉽게 초과 할 수 있습니다.
|
|
|
|
---
|
|
|
|
## 사용 가능
|
|
|
|
`mcp`에서 MCP 서버를 정의할 수 있습니다. 각 MCP를 고유 이름으로 추가합니다. LLM을 프롬프트할 때 MCP를 참조할 수 있습니다.
|
|
|
|
```jsonc title="opencode.jsonc" {6}
|
|
{
|
|
"$schema": "https://opencode.ai/config.json",
|
|
"mcp": {
|
|
"name-of-mcp-server": {
|
|
// ...
|
|
"enabled": true,
|
|
},
|
|
"name-of-other-mcp-server": {
|
|
// ...
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
`enabled`를 `false`로 설정하여 서버를 비활성화 할 수 있습니다. config에서 제거하지 않고 서버를 일시적으로 비활성화하려는 경우 유용합니다.
|
|
|
|
---
|
|
|
|
### 원격 디폴트 overriding
|
|
|
|
조직은 `.well-known/opencode` 엔드포인트를 통해 기본 MCP 서버를 제공 할 수 있습니다. 이 서버는 기본적으로 비활성화 될 수 있으며 사용자가 필요한 것들에 대해 선택 할 수 있습니다.
|
|
|
|
조직의 원격 설정에서 특정 서버를 활성화하려면 `enabled: true`로 로컬 구성에 추가하십시오.
|
|
|
|
```json title="opencode.json"
|
|
{
|
|
"$schema": "https://opencode.ai/config.json",
|
|
"mcp": {
|
|
"jira": {
|
|
"type": "remote",
|
|
"url": "https://jira.example.com/mcp",
|
|
"enabled": true
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
로컬 설정 값은 원격 기본값을 무시합니다. 자세한 내용은 [config precedence](/docs/config#precedence-order)를 참조하십시오.
|
|
|
|
---
|
|
|
|
## 지역
|
|
|
|
MCP 객체 내에서 `type`를 `"local"`로 사용하는 로컬 MCP 서버를 추가하십시오.
|
|
|
|
```jsonc title="opencode.jsonc" {15}
|
|
{
|
|
"$schema": "https://opencode.ai/config.json",
|
|
"mcp": {
|
|
"my-local-mcp-server": {
|
|
"type": "local",
|
|
// Or ["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`](https://www.npmjs.com/package/@modelcontextprotocol/server-everything) MCP 서버를 추가할 수 있는 방법입니다.
|
|
|
|
```jsonc title="opencode.jsonc"
|
|
{
|
|
"$schema": "https://opencode.ai/config.json",
|
|
"mcp": {
|
|
"mcp_everything": {
|
|
"type": "local",
|
|
"command": ["npx", "-y", "@modelcontextprotocol/server-everything"],
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
그리고 `use the mcp_everything tool`를 내 프롬프트에 추가할 수 있습니다.
|
|
|
|
```txt "mcp_everything"
|
|
use the mcp_everything tool to add the number 3 and 4
|
|
```
|
|
|
|
---
|
|
|
|
#### 옵션
|
|
|
|
로컬 MCP 서버를 구성하는 모든 옵션이 있습니다.
|
|
|
|
| 옵션 | 유형 |필수 | 설명 |
|
|
| ------------- | ------- | -------- | ----------------------------------------------------------------------------------- |
|
|
| `type` | 문자열 | Y | MCP 서버 연결 유형은 `"local"`. |
|
|
| `command` | Array | Y | MCP 서버를 실행하는 명령과 인수. |
|
|
| `environment` | 개체 | | 서버 실행시 설정하는 환경 변수
|
|
| `enabled` | Boolean | | 시동에서 MCP 서버 사용 가능 |
|
|
| `timeout` | Number | | MCP 서버에서 태핑툴을 위한 타임아웃 기본 5000 (5 초). |
|
|
|
|
---
|
|
|
|
## 리모트
|
|
|
|
`type`를 `"remote"`로 설정하여 원격 MCP 서버를 추가하십시오.
|
|
|
|
```json title="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` | 문자열 | Y | MCP 서버 연결 유형은 `"remote"`. |
|
|
| `url` | 문자열 | Y | 원격 MCP 서버의 URL. |
|
|
| `enabled` | Boolean | | 시동에서 MCP 서버 사용 가능 |
|
|
| `headers` | 개체 | | 헤드러는 요청으로 보내드립니다. |
|
|
| `oauth` | 개체 | | OAuth 인증 구성 [OAuth](#oauth) 아래의 섹션을 참조하십시오. |
|
|
| `timeout` | Number | | MCP 서버에서 태핑툴을 위한 타임아웃 기본 5000 (5 초). |
|
|
|
|
---
|
|
|
|
## 오아우트
|
|
|
|
OpenCode는 원격 MCP 서버에 대한 OAuth 인증을 자동으로 처리합니다. 서버가 인증이 필요할 때, OpenCode는:
|
|
|
|
1. 401 응답을 검출하고 OAuth 흐름을 시작
|
|
2. **Dynamic Client 등록 (RFC 7591) ** 서버에서 지원되는 경우
|
|
3. 미래의 요청에 대해 안전하게 보관 토큰
|
|
|
|
---
|
|
|
|
## 자동
|
|
|
|
대부분의 OAuth-enabled MCP 서버를 위해, 특별한 윤곽은 필요하지 않습니다. 원격 서버를 구성:
|
|
|
|
```json title="opencode.json"
|
|
{
|
|
"$schema": "https://opencode.ai/config.json",
|
|
"mcp": {
|
|
"my-oauth-server": {
|
|
"type": "remote",
|
|
"url": "https://mcp.example.com/mcp"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
서버가 인증이 필요한 경우, OpenCode는 먼저 사용하려고 할 때 인증됩니다. 그렇지 않다면, `opencode mcp auth <server-name>`를 사용하여 [manually 방아쇠](#authenticating)을 유발할 수 있습니다.
|
|
|
|
---
|
|
|
|
### 사전등록
|
|
|
|
MCP 서버 공급자의 클라이언트 자격이있는 경우, 구성 할 수 있습니다.
|
|
|
|
```json title="opencode.json" {7-11}
|
|
{
|
|
"$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 서버와 인증:
|
|
|
|
```bash
|
|
opencode mcp auth my-oauth-server
|
|
```
|
|
|
|
모든 MCP 서버를 나열하고 auth 상태:
|
|
|
|
```bash
|
|
opencode mcp list
|
|
```
|
|
|
|
저장된 자격 제거:
|
|
|
|
```bash
|
|
opencode mcp logout my-oauth-server
|
|
```
|
|
|
|
`mcp auth` 명령은 사용자의 브라우저를 엽니다. `~/.local/share/opencode/mcp-auth.json`에서 토큰을 안전하게 저장합니다.
|
|
|
|
---
|
|
|
|
### # OAuth를 해제
|
|
|
|
서버의 자동 OAuth를 비활성화하려는 경우 (예를 들어, 대신 API 키를 사용하는 서버), `oauth`를 `false`로 설정:
|
|
|
|
```json title="opencode.json" {7}
|
|
{
|
|
"$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` | 개체 \| false | OAuth config object, 또는 `false`를 비활성화하는 OAuth 자동검출. ·
|
|
| `clientId` | 문자열 | OAuth 클라이언트 ID. 제공되지 않은 경우, 동적 클라이언트 등록 시도됩니다. ·
|
|
| `clientSecret` | String | OAuth 클라이언트 비밀, 허가서 서버가 필요한 경우. |
|
|
| `scope` | String | OAuth 범위는 인증 중입니다. |
|
|
|
|
# # # # # # 디버깅
|
|
|
|
원격 MCP 서버가 인증에 실패하면 다음과 같은 문제를 진단 할 수 있습니다.
|
|
|
|
```bash
|
|
# View auth status for all OAuth-capable servers
|
|
opencode mcp auth list
|
|
|
|
# Debug connection and OAuth flow for a specific server
|
|
opencode mcp debug my-oauth-server
|
|
```
|
|
|
|
`mcp debug` 명령은 현재 auth 상태를 보여 주며 HTTP 연결을 테스트하고 OAuth 발견 흐름을 시도합니다.
|
|
|
|
---
|
|
|
|
## 관리
|
|
|
|
MCP는 OpenCode의 도구로 사용할 수 있으며 내장 도구와 함께 사용할 수 있습니다. 다른 도구와 같이 OpenCode config를 통해 관리할 수 있습니다.
|
|
|
|
---
|
|
|
|
## 글로벌
|
|
|
|
이것은 당신이 활성화하거나 전 세계적으로 비활성화 할 수 있다는 것을 의미합니다.
|
|
|
|
```json title="opencode.json" {14}
|
|
{
|
|
"$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
|
|
}
|
|
}
|
|
```
|
|
|
|
우리는 또한 모든 일치 MCPs를 비활성화하는 glob 패턴을 사용할 수 있습니다.
|
|
|
|
```json title="opencode.json" {14}
|
|
{
|
|
"$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
|
|
}
|
|
}
|
|
```
|
|
|
|
여기에 우리는 모든 MCP를 비활성화하는 glob 패턴 `my-mcp*`를 사용합니다.
|
|
|
|
---
|
|
|
|
## 대리인 당 ##
|
|
|
|
MCP 서버의 많은 수를 가지고 있다면 에이전트 당만 활성화하고 전 세계적으로 비활성화 할 수 있습니다. 이 작업을 수행:
|
|
|
|
1. 글로벌 도구로 사용 가능.
|
|
2. [agent config](/docs/agents#tools)에서 MCP 서버를 도구로 사용할 수 있습니다.
|
|
|
|
```json title="opencode.json" {11, 14-18}
|
|
{
|
|
"$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 패턴은 간단한 regex globbing 패턴을 사용합니다 :
|
|
|
|
- `*`는 어떤 특성 (예를들면, `"my-mcp*"` 경기 `my-mcp_search`, `my-mcp_list`, 등)의 0개 이상 일치합니다.
|
|
- `?`는 정확히 하나의 문자 일치
|
|
- 다른 모든 문자 일치 말 그대로
|
|
|
|
:::note
|
|
MCP 서버 도구는 서버 이름으로 prefix로 등록되므로 서버의 모든 도구를 간단하게 사용할 수 있습니다.
|
|
|
|
```
|
|
"mymcpservername_*": false
|
|
```
|
|
|
|
:::
|
|
|
|
---
|
|
|
|
## 예제
|
|
|
|
다음은 일반적인 MCP 서버의 예입니다. 다른 서버에 문서를 작성하려면 PR을 제출할 수 있습니다.
|
|
|
|
---
|
|
|
|
# # # # 센트리
|
|
|
|
[Sentry MCP 서버](https://mcp.sentry.dev)를 추가하여 센트리 프로젝트와 문제와 상호 작용합니다.
|
|
|
|
```json title="opencode.json" {4-8}
|
|
{
|
|
"$schema": "https://opencode.ai/config.json",
|
|
"mcp": {
|
|
"sentry": {
|
|
"type": "remote",
|
|
"url": "https://mcp.sentry.dev/mcp",
|
|
"oauth": {}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
구성을 추가 한 후, Sentry로 인증:
|
|
|
|
```bash
|
|
opencode mcp auth sentry
|
|
```
|
|
|
|
브라우저 창을 열어 OAuth 흐름을 완료하고 OpenCode를 Sentry 계정에 연결하십시오.
|
|
|
|
일단 인증되면, 당신은 쿼리 문제, 프로젝트, 오류 데이터에 대한 프린트 도구를 사용할 수 있습니다.
|
|
|
|
```txt "use sentry"
|
|
Show me the latest unresolved issues in my project. use sentry
|
|
```
|
|
|
|
---
|
|
|
|
### 콘텍스트7
|
|
|
|
[Context7 MCP 서버](https://github.com/upstash/context7)을 추가하여 문서를 검색합니다.
|
|
|
|
```json title="opencode.json" {4-7}
|
|
{
|
|
"$schema": "https://opencode.ai/config.json",
|
|
"mcp": {
|
|
"context7": {
|
|
"type": "remote",
|
|
"url": "https://mcp.context7.com/mcp"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
무료 계정으로 가입한 경우 API 키를 사용하여 더 높은 속도 제한을 얻을 수 있습니다.
|
|
|
|
```json title="opencode.json" {7-9}
|
|
{
|
|
"$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` 환경 변수 세트가 있다는 것을 assuming입니다.
|
|
|
|
Context7 MCP 서버를 사용하여 `use context7`를 신속하게 추가하십시오.
|
|
|
|
```txt "use context7"
|
|
Configure a Cloudflare Worker script to cache JSON API responses for five minutes. use context7
|
|
```
|
|
|
|
대안으로, 당신은이 같은 뭔가를 추가 할 수 있습니다 [AGENTS.md](/docs/rules/).
|
|
|
|
```md title="AGENTS.md"
|
|
When you need to search docs, use `context7` tools.
|
|
```
|
|
|
|
---
|
|
|
|
## Grep by Vercel에 의해
|
|
|
|
[Grep by Vercel](https://grep.app) MCP 서버를 추가하여 GitHub에서 코드 스니펫을 검색합니다.
|
|
|
|
```json title="opencode.json" {4-7}
|
|
{
|
|
"$schema": "https://opencode.ai/config.json",
|
|
"mcp": {
|
|
"gh_grep": {
|
|
"type": "remote",
|
|
"url": "https://mcp.grep.app"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
MCP 서버 `gh_grep`라는 이름으로, `use the gh_grep tool`를 추가할 수 있습니다.
|
|
|
|
```txt "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](/docs/rules/).
|
|
|
|
```md title="AGENTS.md"
|
|
If you are unsure how to do something, use `gh_grep` to search code examples from GitHub.
|
|
```
|