한국어
문서
MCP 서버

MCP 서버

로컬 및 원격 MCP 도구를 추가합니다.

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

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

주의사항

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

MCP 서버는 컨텍스트에 추가되므로 어떤 것을 활성화할지 신중하게 선택하세요.

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

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

로컬

MCP 객체 내에서 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",
      },
    },
  },
}

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 서버를 구성하기 위한 모든 옵션은 다음과 같습니다.

옵션타입필수설명
typeString예MCP 서버 연결 유형, "local"이어야 합니다.
commandArray예MCP 서버를 실행하기 위한 명령어와 인수.
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 옵션으로 헤더 목록을 전달할 수 있습니다.

옵션

옵션타입필수설명
typeString예MCP 서버 연결 유형, "remote"이어야 합니다.
urlString예원격 MCP 서버의 URL.
enabledBoolean시작 시 MCP 서버 활성화 또는 비활성화.
headersObject요청과 함께 보낼 헤더.
oauthObjectOAuth 인증 구성. 아래 OAuth 섹션 참조.
timeoutNumberMCP 서버에서 도구를 가져오는 타임아웃(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는 처음 사용하려고 할 때 인증하라는 메시지를 표시합니다. 그렇지 않으면 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. 제공되지 않으면 동적 클라이언트 등록이 시도됩니다.
clientSecretString인증 서버에서 요구하는 경우 OAuth 클라이언트 시크릿.
scopeString인증 중 요청할 OAuth 스코프.

디버깅

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

# 모든 OAuth 지원 서버의 인증 상태 보기
opencode mcp auth list
 
# 특정 서버의 연결 및 OAuth 플로우 디버그
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 서버가 많은 경우 전역적으로 비활성화하고 에이전트별로만 활성화할 수 있습니다. 이렇게 하려면:

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

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

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 지원