콘텐츠로 이동
OpenCode
app.header.homeapp.header.docs

MCP servers

Add local and remote MCP tools.

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

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

주의사항

MCP 서버를 사용할 때 상황에 추가합니다. 도구가 많이 있으면 신속하게 추가 할 수 있습니다. 그래서 우리는 당신이 사용하는 MCP 서버와 주의를 기울여야 합니다.

GitHub MCP 서버와 같은 특정 MCP 서버는 많은 토큰을 추가하고 컨텍스트 제한을 쉽게 초과 할 수 있습니다.

사용 가능

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로 설정하여 서버를 비활성화 할 수 있습니다. config에서 제거하지 않고 서버를 일시적으로 비활성화하려는 경우 유용합니다.

원격 디폴트 overriding

조직은 .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
    }
  }
}

로컬 설정 값은 원격 기본값을 무시합니다. 자세한 내용은 config precedence를 참조하십시오.

지역

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

명령은 로컬 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문자열YMCP 서버 연결 유형은 "local".
commandArrayYMCP 서버를 실행하는 명령과 인수.
environment개체서버 실행시 설정하는 환경 변수
enabledBoolean시동에서 MCP 서버 사용 가능
timeoutNumberMCP 서버에서 태핑툴을 위한 타임아웃 기본 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문자열YMCP 서버 연결 유형은 "remote".
url문자열Y원격 MCP 서버의 URL.
enabledBoolean시동에서 MCP 서버 사용 가능
headers개체헤드러는 요청으로 보내드립니다.
oauth개체OAuth 인증 구성 OAuth 아래의 섹션을 참조하십시오.
timeoutNumberMCP 서버에서 태핑툴을 위한 타임아웃 기본 5000 (5 초).

OAuth

opencode는 원격 MCP 서버에 대한 OAuth 인증을 자동으로 처리합니다. 서버가 인증이 필요할 때, opencode는:

  1. 401 응답을 검출하고 OAuth 흐름을 시작
  2. **Dynamic Client 등록 (RFC 7591) ** 서버에서 지원되는 경우
  3. 미래의 요청에 대해 안전하게 보관 토큰

자동

대부분의 OAuth-enabled 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>를 사용하여 manually 방아쇠을 유발할 수 있습니다.

사전등록

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 서버와 인증:

Terminal window
opencode mcp auth my-oauth-server

모든 MCP 서버를 나열하고 auth 상태:

Terminal window
opencode mcp list

저장된 자격 제거:

Terminal window
opencode mcp logout my-oauth-server

mcp auth 명령은 사용자의 브라우저를 엽니다. ~/.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 옵션

옵션유형설명
oauth개체 | falseOAuth config object, 또는 false를 비활성화하는 OAuth 자동검출. ·
clientId문자열OAuth 클라이언트 ID. 제공되지 않은 경우, 동적 클라이언트 등록 시도됩니다. ·
clientSecretStringOAuth 클라이언트 비밀, 허가서 서버가 필요한 경우.
scopeStringOAuth 범위는 인증 중입니다.
디버깅

원격 MCP 서버가 인증에 실패하면 다음과 같은 문제를 진단 할 수 있습니다.

Terminal window
# 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를 통해 관리할 수 있습니다.

글로벌

이것은 당신이 활성화하거나 전 세계적으로 비활성화 할 수 있다는 것을 의미합니다.

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

우리는 또한 모든 일치 MCPs를 비활성화하는 glob 패턴을 사용할 수 있습니다.

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

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

에이전트 당

MCP 서버의 많은 수를 가지고 있다면 에이전트 당만 활성화하고 전 세계적으로 비활성화 할 수 있습니다. 이 작업을 수행:

  1. 글로벌 도구로 사용 가능.
  2. agent config에서 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 패턴은 간단한 regex globbing 패턴을 사용합니다 :

  • *는 어떤 특성 (예를들면, "my-mcp*" 경기 my-mcp_search, my-mcp_list, 등)의 0개 이상 일치합니다.
  • ?는 정확히 하나의 문자 일치
  • 다른 모든 문자 일치 말 그대로

예제

다음은 일반적인 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로 인증:

Terminal window
opencode mcp auth sentry

브라우저 창을 열어 OAuth 흐름을 완료하고 opencode를 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 키를 사용하여 더 높은 속도 제한을 얻을 수 있습니다.

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 환경 변수 세트가 있다는 것을 assuming입니다.

Context7 MCP 서버를 사용하여 use context7를 신속하게 추가하십시오.

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