Bencher MCP 사용 방법

Bencher MCP는 호스팅된 Model Context Protocol(MCP) 서버입니다. bencher CLI를 설치하지 않고도 AI 에이전트와 어시스턴트가 벤치마크 데이터를 조회하고 벤치마크 결과를 제출할 수 있습니다.

bencher CLI를 사용할 수 있다면 여전히 CLI가 Bencher를 사용하는 권장 방법입니다. bencher run은 벤치마크 하네스 어댑터, 반복 실행, CI 통합을 처리합니다. CLI가 설치되어 있지 않거나 MCP 클라이언트가 셸 명령을 실행할 수 없을 때 Bencher MCP를 사용하세요.

연결

Bencher는 claude.ai, Claude Desktop, Claude Mobile, Claude Code에서 사용하는 Claude 커넥터 디렉터리에 등록되어 있습니다. Bencher 커넥터를 추가하고, Claude가 요청하면 Bencher 계정으로 로그인하세요. Claude Code는 claude.ai 구독으로 로그인되어 있으면 claude.ai에서 추가한 커넥터를 사용합니다. 이 커넥터는 Bencher Cloud에만 연결됩니다.

Bencher는 ChatGPT와 Codex에서 사용하는 OpenAI 플러그인 디렉터리에 등록되어 있습니다. Bencher 플러그인을 추가하고, 요청을 받으면 Bencher 계정으로 로그인하세요. Codex에서는 플러그인이 Bencher 스킬도 함께 제공하므로 Codex가 bencher CLI를 실행할 수 있습니다. 이 플러그인은 Bencher Cloud에만 연결됩니다.

기타 MCP 클라이언트, claude.ai 구독으로 로그인하지 않은 Claude Code, Bencher Self-Hosted, CI에서는 대신 URL을 사용하세요:

MCP 클라이언트에 URL을 추가하고, 클라이언트가 요청하면 Bencher 계정으로 로그인하세요. Claude Code는 OAuth로 로그인하며, Bencher Self-Hosted 서버를 URL로 추가하면 ChatGPT와 claude.ai도 OAuth로 로그인합니다. 예를 들어 Claude Code에서 연결하려면:

claude mcp add --transport http bencher https://mcp.bencher.dev/mcp

도구가 로그인을 요구하면 Claude Code에서 /mcp를 실행하고 브라우저의 안내를 따르세요.

대신 API 키로 연결하려면 Authorization 헤더로 보내세요:

claude mcp add --transport http bencher https://mcp.bencher.dev/mcp \
  --header "Authorization: Bearer $BENCHER_API_KEY"

또는 일반적인 MCP 클라이언트 구성을 사용하세요:

{
  "mcpServers": {
    "bencher": {
      "type": "http",
      "url": "https://mcp.bencher.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${BENCHER_API_KEY}"
      }
    }
  }
}

인증

OAuth로 로그인

OAuth를 지원하는 MCP 클라이언트는 Bencher 계정으로 로그인하므로 클라이언트에 키를 붙여 넣을 필요가 없습니다. 클라이언트는 연결할 때 또는 도구가 처음으로 로그인을 요구할 때 브라우저에서 Bencher를 엽니다. Bencher는 앱을 웹 주소로 표시하고 앱이 요청하는 작업을 나열합니다. 로그인하거나 사용자 API 키(bencher_user_*)를 붙여 넣은 다음 승인하거나 거부하세요. Bencher는 앱이 연결할 때마다 확인을 요청하며, 프로젝트 API 키(bencher_run_*)로는 승인할 수 없습니다.

앱은 최대 1년 동안 연결된 상태로 유지됩니다. 사용자 API 키로 승인한 앱은 해당 키가 폐기되거나 만료되는 즉시 연결이 끊어집니다. OAuth 액세스 토큰은 Bencher MCP용입니다: Bencher API는 401 Unauthorized로 거부합니다.

Bencher Self-Hosted에서는 API 서버의 plus.oauth 섹션을 구성하면 로그인할 수 있습니다. ChatGPT와 claude.ai는 인터넷에서 서버에 접근할 수 있어야 합니다. Claude Code는 서버가 Claude Code의 클라이언트 메타데이터 문서를 가져올 수 있거나 plus.oauth.clients에 구성되어 있다면 자체 네트워크에서 https로 제공되는 서버에도 로그인할 수 있습니다.

스코프

앱이 요청하는 스코프는 모두 승인하거나 하나도 승인하지 않습니다:

읽기 도구(list_*, view_*, query_perf)에는 projects:read가 필요합니다. 그 밖의 모든 도구에는 projects:read를 포함하는 projects:write가 필요합니다. 둘 다 요청하지 않는 앱은 projects:read를 받습니다. projects:write 없이 로그인한 앱은 쓰기 도구를 호출하면 다시 로그인하라는 요청을 받습니다. openid, email, profile 스코프는 OpenID Connect용이며, 서버에 plus.oauth.signing_key가 있을 때만 사용할 수 있습니다. 앱은 사용자로서 동작합니다: 각 프로젝트에서 무엇을 보고 변경할 수 있는지는 여전히 사용자의 역할이 결정하며, 앱은 서버 관리자 권한을 갖지 않습니다.

연결된 앱

계정에 연결된 앱을 보려면 Bencher Console의 계정 메뉴에서 Connected Apps를 열거나 /console/users/apps로 이동하세요. 각 앱은 웹 주소로 표시되며, 할 수 있는 일, 연결한 시점, 마지막으로 액세스를 갱신한 시점, 승인한 방법이 함께 표시됩니다. Revoke를 누르면 앱의 연결이 즉시 끊어집니다.

API 키

Bencher MCP는 Bencher API와 동일한 Authorization: Bearer 자격 증명도 허용합니다: 프로젝트 API 키(bencher_run_*) 또는 사용자 API 키(bencher_user_*)입니다. 프로젝트 API 키는 단일 프로젝트로 범위가 제한되므로 대부분의 에이전트에 가장 적합한 선택입니다. 사용자 API 키는 사용자의 모든 프로젝트에 접근할 수 있습니다. 유효하지 않은 자격 증명은 모든 요청에서 거부되며, 익명으로 처리되지 않습니다.

로그인하지 않고

공개 프로젝트는 자격 증명 없이 읽을 수 있습니다. 익명 요청은 IP 주소별 요청 제한을 함께 사용하고, 로그인한 요청은 사용자 자신의 제한에 계산됩니다. 서버에 OAuth가 구성되어 있으면, 익명 도구 호출에 로그인이 필요할 때 Bencher MCP가 클라이언트에 로그인을 요청합니다:

• 비공개 프로젝트를 읽을 때. 존재하지 않는 프로젝트도 같은 응답을 받으므로, 공개 프로젝트 안에서라도 프로젝트나 ID를 잘못 입력하면 로그인을 요청받습니다.
• 쓰기 도구를 호출할 때. 단, unclaimed 프로젝트에 대한 submit_run은 제외됩니다.
• list_projects로 조직의 프로젝트를 나열할 때.
• 익명 요청 제한을 초과할 때.

도구

도구 범위는 프로젝트 API 키(bencher_run_*)로 수행할 수 있는 작업을 반영합니다: 프로젝트 범위의 읽기와 쓰기이며, 삭제 도구는 없습니다. 이름 변경 도구도 없으며, 프로젝트 API 키로는 알림 업데이트가 상태 변경으로 제한됩니다. 대부분의 도구는 프로젝트 슬러그 또는 UUID를 받는 project 인수를 사용합니다.