한국어
문서
MCP 서버

MCP 서버

로컬 및 원격 MCP 도구를 추가하세요.

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

추가되면, MCP 도구는 내장 도구와 함께 LLM이 자동으로 사용할 수 있게 됩니다.

주의사항

MCP 서버를 사용하면 컨텍스트에 추가됩니다. 도구가 많으면 이는 빠르게 누적될 수 있습니다. 따라서 사용하는 MCP 서버를 신중히 선택하는 것을 권장합니다.

Tip: MCP 서버는 컨텍스트에 추가되므로, 활성화할 서버를 신중히 선택해야 합니다.

GitHub MCP 서버 같은 특정 MCP 서버는 많은 토큰을 추가하는 경향이 있어 컨텍스트 한도를 쉽게 초과할 수 있습니다.

활성화

OpenCode Config (opens in a new tab)의 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
    }
  }
}

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

로컬

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

opencode.jsonc
{
  "$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",
      },
    },
  },
}

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

예를 들어, 테스트용 @modelcontextprotocol/server-everything (opens in a new tab) 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 서버를 설정하기 위한 모든 옵션입니다.

옵션타입필수설명
typeStringYMCP 서버 연결 타입, "local"이어야 합니다.
commandArrayYMCP 서버를 실행하는 명령과 인수.
environmentObject서버 실행 시 설정할 환경 변수.
enabledBoolean시작 시 MCP 서버 활성화 또는 비활성화.
timeoutNumberMCP 서버에서 도구를 가져오기 위한 타임아웃(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 옵션으로 헤더 목록을 전달할 수 있습니다.

옵션

옵션타입필수설명
typeStringYMCP 서버 연결 타입, "remote"여야 합니다.
urlStringY원격 MCP 서버의 URL.
enabledBoolean시작 시 MCP 서버 활성화 또는 비활성화.
headersObject요청과 함께 보낼 헤더.
oauthObjectOAuth 인증 설정. 아래 OAuth 섹션을 참조하세요.
timeoutNumberMCP 서버에서 도구를 가져오기 위한 타임아웃(ms). 기본값은 5000(5초).

OAuth

OpenCode는 원격 MCP 서버의 OAuth 인증을 자동으로 처리합니다. 서버가 인증을 요구하면, OpenCode는 다음을 수행합니다:

  1. 401 응답을 감지하고 OAuth 흐름을 시작합니다
  2. 서버가 지원하는 경우 **Dynamic Client Registration (RFC 7591)**을 사용합니다
  3. 향후 요청을 위해 토큰을 안전하게 저장합니다

자동

대부분의 OAuth 지원 MCP 서버는 특별한 설정이 필요 없습니다. 원격 서버만 설정하면 됩니다:

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>으로 수동으로 흐름을 트리거할 수 있습니다.

사전 등록

MCP 서버 제공자로부터 클라이언트 자격 증명을 받은 경우, 다음과 같이 설정할 수 있습니다:

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 비활성화

서버의 자동 OAuth를 비활성화하려면(예: API 키를 대신 사용하는 서버), 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 옵션

옵션타입설명
oauthObject | falseOAuth 설정 객체, 또는 OAuth 자동 감지를 비활성화하려면 false.
clientIdStringOAuth 클라이언트 ID. 제공되지 않으면 동적 클라이언트 등록을 시도합니다.
clientSecretStringOAuth 클라이언트 시크릿, 인증 서버가 요구하는 경우.
scopeString인증 중에 요청할 OAuth 스코프.

디버깅

원격 MCP 서버 인증이 실패하는 경우, 다음으로 문제를 진단할 수 있습니다:

# 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 명령은 현재 인증 상태를 표시하고, HTTP 연결을 테스트하며, OAuth 디스커버리 흐름을 시도합니다.

관리

MCP는 내장 도구와 함께 OpenCode에서 도구로 사용할 수 있습니다. 따라서 다른 도구와 마찬가지로 OpenCode 설정을 통해 관리할 수 있습니다.

전역

이는 전역적으로 활성화하거나 비활성화할 수 있음을 의미합니다.

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
  }
}

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

에이전트별

MCP 서버가 많은 경우 전역적으로 비활성화하고 에이전트별로만 활성화하고 싶을 수 있습니다. 이를 위해:

  1. 전역적으로 도구로서 비활성화합니다.
  2. 에이전트 설정에서 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 패턴은 단순한 정규식 globbing 패턴을 사용합니다:

  • *는 모든 문자의 0개 이상과 매칭(예: "my-mcp*"는 my-mcp_search, my-mcp_list 등과 매칭)
  • ?는 정확히 한 문자와 매칭
  • 다른 모든 문자는 문자 그대로 매칭

Note: MCP 서버 도구는 서버 이름을 접두사로 하여 등록되므로, 서버의 모든 도구를 비활성화하려면 간단히 다음을 사용하세요:

"mymcpservername_*": false

예시

아래는 몇 가지 일반적인 MCP 서버의 예시입니다. 다른 서버를 문서화하고 싶다면 PR을 제출할 수 있습니다.

Sentry

Sentry MCP 서버 (opens in a new tab)를 추가하여 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 서버 (opens in a new tab)를 추가하여 문서를 검색하세요.

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

무료 계정에 가입한 경우, API 키를 사용하여 더 높은 속도 제한을 얻을 수 있습니다.

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에 다음과 같은 내용을 추가할 수 있습니다.

AGENTS.md
When you need to search docs, use `context7` tools.

Grep by Vercel

Grep by Vercel (opens in a new tab) 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에 다음과 같은 내용을 추가할 수 있습니다.

AGENTS.md
If you are unsure how to do something, use `gh_grep` to search code examples from GitHub.
LSP 서버ACP 지원