Servidor MCP do GitHub: configuração, uso de tokens e limites de taxa sem surpresas

Conecte o servidor MCP do GitHub ao seu editor e um agente de IA pode ler issues, revisar pull requests e abrir branches em seu nome. Ele também carrega uma longa lista de definições de ferramentas em cada conversa e consome o orçamento de requisições do token que você fornecer. Três coisas decidem se a configuração parece tranquila ou dolorosa: como você se conecta, quantos tokens de contexto o servidor consome e quais limites de taxa você atinge primeiro.

Todos os números abaixo vêm da própria documentação do GitHub ou de medições da comunidade publicadas em 2026, e cada um está identificado como tal. As contagens de tokens, em especial, mudam entre versões do servidor, então trate-as como faixas e não como promessas. O mesmo vale para qualquer número que você leia sobre ferramentas MCP: verifique a versão em que ele foi medido antes de montar um orçamento com base nele.

💡 Resumo rápido: use o servidor remoto, dê a ele um token restrito, ative apenas os toolsets que você usa e espere pelo menos um minuto quando o GitHub responder com 403 ou 429.

Servidor remoto ou local?

As duas opções expõem as mesmas ferramentas do GitHub. O que muda é quem executa o processo e como você faz login. Se escolher a errada, você acaba mantendo o Docker em cinco notebooks ou esperando o GitHub liberar um recurso de que precisava ontem.

Noções básicas do servidor remoto

O GitHub hospeda o servidor remoto em https://api.githubcopilot.com/mcp/. Seu cliente aponta para essa URL e você faz login pelo navegador com OAuth, ou envia um token de acesso pessoal em um cabeçalho Authorization. Não há nada para instalar nem para atualizar, porque as novas ferramentas chegam no cronograma do GitHub, não no seu.

O mesmo host oferece uma variante insiders em https://api.githubcopilot.com/mcp/insiders para recursos antecipados. Teste em uma máquina de testes antes de deixá-la mexer na sua configuração diária.

Opção local com Docker

O servidor local é distribuído como a imagem ghcr.io/github/github-mcp-server. Seu cliente o inicia com docker run -i --rm e se comunica com ele por stdio. Você escolhe a versão, controla cada variável de ambiente e pode apontá-lo para o GitHub Enterprise Server com GITHUB_HOST. O preço é ter o Docker em cada máquina e um token guardado em um arquivo de configuração.

Configuração em cinco minutos

Todos os trechos abaixo vêm do README do projeto. Cole um deles, reinicie o cliente e peça ao agente que liste seus pull requests abertos como teste de fumaça. Se a lista aparecer, a conexão funciona e tudo o que vem depois é ajuste fino.

VS Code com OAuth

O caminho mais curto. Não é preciso criar nenhum token nem guardar nenhum segredo.

{
  "servers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  }
}

Copiar prompt

O VS Code abre uma aba do navegador, você aprova o acesso e a credencial fica na memória, em vez de ir parar em um arquivo.

VS Code com token

Use este caminho quando seu cliente não suportar o fluxo OAuth ou quando você quiser um token limitado a escopos específicos.

{
  "servers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${input:github_mcp_pat}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "github_mcp_pat",
      "description": "GitHub Personal Access Token",
      "password": true
    }
  ]
}

Copiar prompt

A flag password: true mascara o valor quando o VS Code o solicita, então o token nunca é gravado no arquivo que você pode acabar commitando.

Configuração do Claude Desktop

O Claude Desktop inicia o servidor local com Docker e entrega o token por meio de uma variável de ambiente:

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
               "ghcr.io/github/github-mcp-server"],
      "env": {"GITHUB_PERSONAL_ACCESS_TOKEN": "your_token_here"}
    }
  }
}

Copiar prompt

Substitua your_token_here por um token real e mantenha este arquivo fora do controle de versão. O Cursor aceita uma estrutura semelhante aos exemplos do VS Code.

💡 Se um token e o OAuth estiverem configurados ao mesmo tempo, o token prevalece. A documentação do projeto diz que GITHUB_PERSONAL_ACCESS_TOKEN tem precedência sobre o OAuth.

Escopos do token de acesso pessoal

O token é a única parte desta configuração que pode prejudicar você. Um agente com um token amplo pode fazer tudo o que esse token permite, inclusive erros que você nunca cometeria manualmente.

Escolha os menores escopos

O README recomenda três escopos:

Comece com repo e adicione os outros apenas quando uma ferramenta falhar com erro de permissão. Se você trabalha em apenas alguns repositórios, um token de granularidade fina restrito a eles é ainda mais seguro. Use um token separado para cada projeto, para que revogar um deles não quebre os demais.

Mantenha os tokens fora do Git

Três hábitos evitam a maioria dos vazamentos:

• Coloque o token em uma variável de ambiente ou em um campo de entrada do prompt, nunca em um arquivo de configuração commitado.
• Restrinja as permissões de qualquer configuração local com chmod 600 ~/.your-app/config.json.
• Troque os tokens periodicamente e revogue um assim que ele aparecer em um diff.

O custo real das definições de ferramentas

Um cliente MCP carrega as definições de cada servidor conectado no contexto do modelo para que ele saiba o que pode chamar. Essa carga conta para a sua janela de contexto em cada requisição, seja o agente usando uma ferramenta ou não. Estimativas da comunidade colocam uma única definição em torno de 300 a 600 tokens, somando o nome, a descrição e o esquema de parâmetros.

O servidor do GitHub tem muitas ferramentas, por isso aparece em toda conversa sobre inchaço de contexto.

O que os números dizem

Estas são medições da comunidade publicadas no dev.to em 2026, não números do GitHub:

Em uma janela de 200.000 tokens, o número de 55.000 representa mais de um quarto do espaço consumido antes de você digitar uma palavra. Os toolsets padrão ficam em torno de 2%. As contagens diferem porque as pessoas mediram versões de servidor e configurações de toolsets diferentes.

O seu cliente também importa. De acordo com um texto de 2026, por padrão, o Claude Code só carrega os esquemas de ferramentas MCP depois de uma etapa de busca de ferramentas, e uma medição relatou uma redução de 46,9% por causa disso. Cursor, Windsurf e Gemini CLI carregam as definições logo no início, então pagam o preço integral.

Reduza com toolsets

Os toolsets ligam ou desligam grupos inteiros de ferramentas. Sem nenhuma configuração, o servidor ativa context, issues, pull_requests, repos e users. O restante da lista é actions, code_quality, code_security, copilot, dependabot, discussions, gists, git, governance, labels, notifications, orgs, projects, secret_protection, security_advisories e stargazers. Os valores especiais all e default fazem exatamente o que o nome indica.

Para o servidor local, defina GITHUB_TOOLSETS:

docker run -e GITHUB_PERSONAL_ACCESS_TOKEN=<token> \
  -e GITHUB_TOOLSETS="repos,issues,pull_requests" \
  ghcr.io/github/github-mcp-server

Copiar prompt

Para o servidor remoto, envie o cabeçalho X-MCP-Toolsets com a mesma lista separada por vírgulas:

{
  "servers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${input:github_mcp_pat}",
        "X-MCP-Toolsets": "repos,issues,pull_requests"
      }
    }
  }
}

Copiar prompt

Dois outros controles ajustam o resultado. GITHUB_TOOLS (ou o cabeçalho X-MCP-Tools) adiciona ferramentas individuais sobre os seus toolsets, por exemplo get_gist sem ativar todo o gists. X-MCP-Exclude-Tools remove ferramentas, e a documentação informa que ferramentas excluídas têm precedência sobre os toolsets e as ferramentas individuais.

💡 Resista à tentação de all. Passar de cerca de 4.200 tokens de definições para cerca de 55.000 traz ferramentas que você provavelmente nunca vai usar, e você paga por elas em toda requisição.

Modos somente leitura e de bloqueio

Duas chaves reduzem o raio de impacto sem mexer nos seus toolsets:

O modo somente leitura funciona como um filtro rígido que prevalece sobre o restante da sua configuração, e as ferramentas desativadas também significam menos definições para carregar. O bloqueio importa quando um agente lê issues ou comentários escritos por desconhecidos, porque é justamente no texto de pessoas sem acesso de push que se escondem instruções hostis. No modo HTTP, depois que um operador ativa o bloqueio no servidor, o cabeçalho X-MCP-Lockdown não consegue mais desativá-lo para uma única requisição.

Limites de taxa que você vai de fato atingir

O servidor chama a API do GitHub com a sua identidade, então os limites que importam são os que o GitHub documenta para a sua API REST. Duas camadas se aplicam: um limite primário por hora e limites secundários por minuto.

Limites primários por hora

Com 5.000 por hora, você tem cerca de 83 chamadas por minuto em média. Um agente que lista as issues de um repositório, abre cada uma e depois lê todos os comentários pode gastar centenas de chamadas em poucos minutos, então o orçamento horário é uma limitação real em sessões grandes de triagem.

Limites secundários por minuto

Os limites secundários existem para conter rajadas, e agentes geram rajadas. O GitHub documenta estes:

• 100 requisições simultâneas no máximo.
• 900 pontos por minuto para endpoints REST.
• 90 segundos de tempo de CPU a cada 60 segundos de tempo real.
• 80 requisições que geram conteúdo por minuto e 500 por hora.
• 2.000 requisições de token de acesso OAuth por hora.

Chamadas de ferramentas em paralelo se acumulam contra o limite de simultaneidade. Um agente que comenta dezenas de issues em um loop atinge o teto de 80 requisições que geram conteúdo por minuto muito antes de chegar ao orçamento horário.

Como corrigir erros 403 e 429

Quando um limite é atingido, o GitHub responde com 403 ou 429. Leia os cabeçalhos da resposta antes de mudar qualquer coisa:

Backoff que funciona

1. Se a resposta trouxer o cabeçalho retry-after, espere essa quantidade de segundos.
2. Caso contrário, espere até o horário indicado em x-ratelimit-reset.
3. Para limites secundários sem cabeçalhos, espere pelo menos um minuto e depois aumente o atraso exponencialmente a cada nova falha.

Inclua a regra também nas instruções do seu agente: quando o GitHub retornar 403 ou 429, pare e informe, em vez de tentar de novo. Um agente que tenta novamente de imediato só gasta mais requisições em um limite que ainda não foi reiniciado.

3 erros comuns

1. Ativar todos os toolsets. O contexto se enche de definições de ferramentas e o agente fica mais lento e menos preciso na escolha das ferramentas.
2. Escrever em loop. Comentários, rótulos ou issues em massa atingem o limite de 80 conteúdos por minuto rapidamente. Divida o trabalho em lotes e faça pausas entre eles.
3. Reutilizar um mesmo token amplo em todos os lugares. Quando ele vaza ou se comporta mal, tudo quebra de uma vez. Dê a cada projeto o seu próprio token restrito.

Coloque um modelo da PicassoIA para trabalhar

O servidor MCP do GitHub devolve material bruto: listas de issues, diffs, threads de comentários. Um modelo de linguagem transforma isso em decisões. O Claude Sonnet 5 na PicassoIA lida com tarefas de programação em várias etapas e uso de ferramentas, lê capturas de tela e permite definir quanto ele deve pensar, o que faz dele um bom segundo par de olhos sobre o que o seu agente do GitHub retorna.

Como usar o Sonnet 5 na PicassoIA

1. Abra o Claude Sonnet 5 na PicassoIA.
2. Cole a lista de issues ou o diff que o seu agente retornou no campo Prompt. Remova antes os tokens e os dados privados.
3. Defina um System Prompt uma vez, por exemplo: "Você revisa pull requests e sinaliza mudanças arriscadas em três tópicos." Reutilize-o em todo o projeto.
4. Escolha o nível de Effort. low é o padrão e o mais rápido, enquanto high ou max se adequa a um bug que afeta vários arquivos.
5. Mantenha Max Tokens em 8.192, a menos que a resposta seja cortada.
6. Anexe uma captura de tela do erro no campo Image quando o texto sozinho não bastar.

A PicassoIA também expõe a própria API para desenvolvedores e um conector MCP, e a mesma lógica de limites se aplica. A API fica em https://api.picassoia.com/v1, aceita credenciais Bearer que começam com pia_sk_ e executa tarefas de forma assíncrona: crie uma predição, consulte o status e depois busque o resultado. Quatro modelos são acessíveis pela API e pelo MCP: PicassoIA Image, PicassoIA Image Editor Pro, PicassoIA Video e Seedance 2.5 Lite. Uma conta pode rodar 5 predições simultâneas, compartilhadas entre credenciais e conexões MCP. A mesma lição das 100 requisições simultâneas do GitHub: o limite de simultaneidade é o primeiro muro que um agente paralelo atinge.

Experimente no Picasso IA

Seu README, notas de versão e templates de issues ficam melhores com uma imagem real no topo. Gere um cabeçalho fotorrealista com o PicassoIA Image e depois ajuste o enquadramento ou corrija um detalhe com o PicassoIA Image Editor Pro.

Três prompts que valem a pena testar hoje:

• Uma mesa de desenvolvedor organizada ao nascer do sol, com notebook, caderno e caneca, fotografada em filme 35mm.
• Um corredor estreito de sala de servidores com luz suave no teto e cabos bem organizados, em grande angular.
• Uma sessão tranquila de revisão de equipe ao redor de uma mesa de madeira, com luz natural de janela.

Escolha um, gere algumas variações e veja qual deixa a página do seu próximo repositório mais marcante. Comece a criar suas próprias imagens com o Picasso IA e experimente até o resultado combinar com o seu projeto.