---
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.
```