Como usar o Bencher MCP

O Bencher MCP é um servidor Model Context Protocol (MCP) hospedado. Ele permite que agentes e assistentes de IA consultem dados de benchmark e enviem resultados sem precisar da CLI bencher instalada.

Quando a CLI bencher está disponível, ela continua sendo a forma recomendada de trabalhar com o Bencher. bencher run cuida dos adaptadores de harness de benchmark, das iterações e da integração com CI. Use o Bencher MCP quando a CLI não estiver instalada ou quando o seu cliente MCP não puder executar comandos de shell.

Conectar

O Bencher está no diretório de conectores do Claude, que atende o claude.ai, o Claude Desktop, o Claude Mobile e o Claude Code. Adicione o conector do Bencher e entre com a sua conta do Bencher quando o Claude pedir. O Claude Code usa os conectores que você adiciona no claude.ai quando entrou com uma assinatura do claude.ai. O conector se conecta apenas ao Bencher Cloud.

O Bencher está no diretório de plugins da OpenAI, que atende o ChatGPT e o Codex. Adicione o plugin do Bencher e entre com a sua conta do Bencher quando for solicitado. No Codex, o plugin também traz o skill do Bencher, para que o Codex possa executar a CLI bencher. O plugin se conecta apenas ao Bencher Cloud.

Em vez disso, use a URL com outros clientes MCP, com o Claude Code sem entrar com uma assinatura do claude.ai, com o Bencher Self-Hosted e em CI:

Adicione a URL ao seu cliente MCP e entre com a sua conta do Bencher quando o cliente pedir. O Claude Code entra com OAuth, assim como o ChatGPT e o claude.ai quando você adiciona um servidor do Bencher Self-Hosted pela URL. Por exemplo, conecte-se pelo Claude Code:

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

Quando uma ferramenta precisar que você entre, execute /mcp no Claude Code e siga as etapas no seu navegador.

Para se conectar com uma chave de API em vez disso, envie-a no cabeçalho Authorization:

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

Ou use uma configuração genérica de cliente MCP:

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

Autenticação

Entrar com OAuth

Clientes MCP que suportam OAuth entram com a sua conta do Bencher, então você nunca precisa colar uma chave neles. O cliente abre o Bencher no seu navegador, seja quando você se conecta ou na primeira vez que uma ferramenta precisa que você entre. O Bencher identifica o aplicativo pelo seu endereço web e lista o que o aplicativo está pedindo para fazer. Entre, ou cole uma chave de API de usuário (bencher_user_*), e então aprove ou negue. O Bencher pergunta toda vez que um aplicativo se conecta, e uma chave de API de projeto (bencher_run_*) não pode aprovar.

Um aplicativo permanece conectado por até um ano. Um aplicativo aprovado com uma chave de API de usuário é desconectado assim que essa chave é revogada ou expira. Tokens de acesso OAuth são para o Bencher MCP: a API do Bencher os recusa com 401 Unauthorized.

No Bencher Self-Hosted, entrar funciona assim que a seção plus.oauth do servidor de API estiver configurada. O ChatGPT e o claude.ai precisam alcançar o servidor pela internet. O Claude Code também pode entrar em um servidor da sua própria rede servido por https, desde que o servidor consiga buscar o documento de metadados de cliente do Claude Code ou o tenha configurado em plus.oauth.clients.

Escopos

Você aprova todos os escopos que um aplicativo pede, ou nenhum deles:

As ferramentas de leitura (list_*, view_*, query_perf e perf_image) precisam de projects:read. Todas as outras ferramentas precisam de projects:write, que inclui projects:read. Um aplicativo que não pede nenhum dos dois recebe projects:read. Um aplicativo que entrou sem projects:write é solicitado a entrar novamente quando chama uma ferramenta que grava. Os escopos openid, email e profile são para OpenID Connect e só estão disponíveis quando o servidor tem um plus.oauth.signing_key. Um aplicativo age como você: o seu papel em cada projeto continua decidindo o que ele pode ver e alterar, e ele nunca tem acesso de administrador do servidor.

Aplicativos conectados

Para ver os aplicativos conectados à sua conta, abra Connected Apps no menu da sua conta no Bencher Console, ou acesse /console/users/apps. Cada aplicativo é listado pelo seu endereço web, com o que ele pode fazer, quando se conectou, quando renovou o acesso pela última vez e como você o aprovou. Revoke desconecta um aplicativo na hora.

Chaves de API

O Bencher MCP também aceita as mesmas credenciais Authorization: Bearer da API do Bencher: uma chave de API de projeto (bencher_run_*) ou uma chave de API de usuário (bencher_user_*). Uma chave de API de projeto tem escopo limitado a um único projeto, sendo a melhor escolha para a maioria dos agentes. Uma chave de API de usuário pode acessar todos os projetos do usuário. Uma credencial que não é válida é recusada em todas as requisições e nunca é tratada como anônima.

Sem entrar

Projetos públicos podem ser lidos sem nenhuma credencial. Requisições anônimas compartilham um limite de taxa por endereço IP, enquanto requisições autenticadas contam para os seus próprios limites. Quando o servidor tem OAuth configurado, o Bencher MCP pede ao seu cliente que entre quando uma chamada anônima de ferramenta precisa disso:

• Ao ler um projeto privado. Um projeto que não existe recebe a mesma resposta, então um projeto ou ID digitado errado, mesmo dentro de um projeto público, também pede que você entre.
• Ao chamar uma ferramenta que grava, exceto submit_run para um projeto unclaimed.
• Ao listar os projetos de uma organização com list_projects.
• Ao ultrapassar o limite de taxa anônimo.

Ferramentas

O conjunto de ferramentas espelha o que uma chave de API de projeto (bencher_run_*) pode fazer: leituras e gravações com escopo de projeto, sem ferramentas de exclusão. Não há ferramentas de renomeação, e com uma chave de API de projeto as atualizações de alertas se limitam ao status. A maioria das ferramentas aceita um argumento project, que pode ser o slug ou o UUID do projeto.