GitHub MCP no Claude Code: quais permissões dar ao token sem abrir o repositório inteiro?

Fala aí, beleza? Plugar o GitHub no Claude Code é um comando de uma linha, e é justamente aí que mora a pegadinha

A parte difícil não é conectar, é decidir o que aquele token pode fazer depois de conectado

E como ninguém quer travar no meio da tarefa, o caminho preguiçoso é sempre o mesmo: marca tudo, dá acesso amplo, segue o baile

Só que aí o agente passa a ter, no papel, a mesma mão livre que você tem no repositório inteiro

Neste post eu separo o acesso em três níveis (só leitura, comentar em issue e PR, escrever no repositório), mostro o que muda na prática em cada um e como configurar o menor escopo que ainda resolve a tarefa

O que você precisa antes de configurar

Pouca coisa, se liga:

• Claude Code instalado e funcionando na sua máquina (se você ainda tá decidindo se vale a pena, dá uma olhada em usar o Claude Code sem saber programar)
• Uma conta do GitHub com um token: o GitHub recomenda o PAT fine-grained no lugar do clássico pro MCP, e o clássico ainda funciona, só que com um comportamento diferente (te conto lá embaixo)
• A escolha do servidor: o remoto oficial vive na URL https://api.githubcopilot.com/mcp/ e está em disponibilidade geral desde 04/09/2025, ou o servidor local, do repositório github/github-mcp-server

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 114 aulas
• 4 projetos
• 9h 18min

Conhecer formação

Por que o tipo de token muda tudo:

Token clássico trabalha com escopos OAuth, aquelas caixinhas largas que você marca na criação

Token fine-grained é outra lógica: permissões nomeadas por recurso, cada uma com nível de leitura ou de escrita

No repositório, as que interessam aqui são Metadata (metadados), Contents (conteúdo do repositório), Issues e Pull requests

É isso que abre espaço pra dizer "pode mexer em issue, mas não encosta no código", com um nível de precisão que a caixinha larga não te dá

Três níveis de escopo: leitura, comentar em issue e PR, escrever no repositório

A forma mais simples de pensar nisso é em degraus: você só sobe um quando a tarefa prova que precisa

O que é verificável aqui é a mecânica: as permissões existem por recurso, com nível de leitura ou de escrita, e quem aplica a regra de verdade é a própria API do GitHub na hora da chamada

Agora o aviso honesto: a documentação oficial não publica uma tabela dizendo qual permissão cada ferramenta do GitHub MCP exige

O pedido segue aberto no repositório oficial, na issue "Clearly Specify Required GitHub Token Permissions per Action"

Ou seja, qualquer post que te entregue esse mapeamento ferramenta por ferramenta tá chutando

Por isso o método aqui é o inverso: começa apertado e afrouxa quando a rotina reclamar

Como configurar o GitHub MCP no Claude Code com o menor escopo

1. Crie o token fine-grained com as permissões do nível escolhido

Se a ideia é revisar código e responder pergunta sobre o repositório, tudo fica em leitura

O erro comum deste passo é já sair marcando escrita "pra não dar problema depois", e aí o degrau mais alto vira o padrão da sua máquina pra sempre

Lembra também que, como não existe tabela oficial de ferramenta por permissão, você não vai descobrir a permissão exata lendo a doc: vai descobrir usando

2. Adicione o servidor remoto no Claude Code

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ --header "Authorization: Bearer SEU_GITHUB_PAT"

O erro comum deste passo é achar que "salvou" significa "funcionou"

O claude mcp add grava a configuração sem validar a credencial, então um token errado (ou um placeholder que você esqueceu de trocar) só falha depois, na hora da conexão

3. Confira o status da conexão

/mcp

O /mcp lista os servidores e o status de conexão de cada um

Esse é o momento de descobrir que o token não presta, e não trinta minutos depois no meio de uma tarefa

4. Ligue o modo somente leitura

No servidor remoto dá pra fazer isso de dois jeitos: pelo header X-MCP-Readonly ou pelo caminho /readonly na URL, que fica assim: https://api.githubcopilot.com/mcp/readonly

Repara na barra: a URL padrão já termina em /, então é mcp/readonly, e não mcp//readonly

claude mcp add --transport http github https://api.githubcopilot.com/mcp/readonly --header "Authorization: Bearer SEU_GITHUB_PAT"

No servidor local, o equivalente é a flag --read-only ou a variável de ambiente GITHUB_READ_ONLY

E aqui vem a parte MUITO boa: o modo somente leitura tem precedência sobre as outras configurações do servidor

Ele age como filtro estrito, ou seja, ferramenta de escrita fica desabilitada mesmo quando você pede ela explicitamente via --tools

O erro comum deste passo é justamente esse: listar uma ferramenta de escrita em --tools e achar que ela sobrepõe o read-only, quando é o contrário

5. Reduza a superfície escolhendo os toolsets

O GitHub MCP agrupa as ferramentas em toolsets, e um conjunto já vem habilitado por padrão: context, issues, pull_requests, repos e users

No remoto, você escolhe quais ficam ativos pelo header X-MCP-Toolsets, que aceita lista separada por vírgula

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ --header "Authorization: Bearer SEU_GITHUB_PAT" --header "X-MCP-Toolsets: context,issues,pull_requests"

O erro comum deste passo é tentar empilhar vários toolsets no caminho da URL: o caminho aceita só um por vez, a lista é coisa do header

Qual escopo escolher para cada tarefa

O mapeamento que eu faria, indo do mais apertado pro mais solto:

• Revisar código e responder perguntas sobre o repositório: somente leitura resolve, e resolve bem
• Triagem e resposta em issues e pull requests: aí sim entram Issues e Pull requests em escrita, com Contents ainda em leitura
• Abrir branch e alterar arquivos: só nesse caso o Contents em escrita se justifica

Repara que o degrau do meio é o mais esquecido, e é o que resolve boa parte da rotina de quem usa agente pra manter repositório vivo

E tem uma segunda camada, que fica do lado do Claude Code, não do GitHub

As regras de permissão são avaliadas em ordem fixa: deny, depois ask, depois allow

O primeiro match nessa ordem decide, e especificidade de regra não muda essa ordem (não adianta escrever a regra mais detalhada do mundo achando que ela "ganha")

Os padrões aceitam glob no nome da ferramenta MCP, no formato mcp__<servidor>__<ferramenta>

A própria doc cita exemplos como mcp__github__get_, pra casar só as ferramentas que começam com get_, e mcp__puppeteer__, pra pegar todas as de um servidor

Se você quer que isso valha em todos os projetos, o lugar é o arquivo de configuração de nível de usuário, em ~/.claude/settings.json

Pensa nisso como cinto e suspensório: o token limita o que é possível na API, a regra de permissão limita o que roda sem te perguntar

Problemas comuns ao restringir o token

O servidor aparece configurado, mas não conecta:

Sintoma: você rodou o claude mcp add, o comando não reclamou de nada, e mesmo assim o servidor não responde

Causa: o add salva a configuração sem validar a credencial, então a falha só aparece na conexão

Solução: rodar /mcp e olhar o status do servidor

Como prevenir: transforma o /mcp em passo obrigatório logo depois de qualquer troca de token, não em coisa que você só lembra quando dá ruim

O agente lista ferramentas que depois falham na chamada:

Sintoma: a ferramenta aparece disponível, o agente tenta usar e leva erro de permissão

Causa: o filtro de escopo do servidor só vale pra PAT clássico (prefixo ghp_), onde ele descobre os escopos na inicialização e esconde as ferramentas sem permissão

PAT fine-grained (github_pat_), token de instalação de GitHub App e token server-to-server não passam por essa detecção, então o servidor exibe todas as ferramentas

A permissão continua valendo, ela só é aplicada mais tarde, pela API do GitHub, na hora da chamada

Solução: tratar a lista de ferramentas como catálogo, não como promessa

Como prevenir: anota qual nível de escopo aquele token tem e usa as regras de permissão do Claude Code pra bloquear o que você sabe que não vai passar

A regra de allow não aprova nada:

Sintoma: você escreveu uma regra de allow bem abrangente e o Claude Code continua perguntando

Causa: allow exige que o nome do servidor seja literal

O glob só vale depois do prefixo mcp__<servidor>__, então uma regra sem âncora, tipo ou mcp__, é ignorada com aviso e não aprova nada automaticamente

Solução: ancorar no servidor, no estilo mcp__github__get_*

Como prevenir: escrever allow sempre por família de ferramenta, nunca por curinga solto

Conclusão

A lógica do post inteiro cabe em uma frase: sobe o escopo só quando a tarefa provar que precisa, nunca antes

Somente leitura pra entender o repositório, escrita em Issues e Pull requests quando o trabalho é de triagem e conversa, Contents em escrita só quando o agente realmente vai mexer no código

E tem duas camadas extras que valem conhecer, principalmente se o repositório é público

A primeira é o lockdown mode, ligado pela variável GITHUB_LOCKDOWN_MODE no servidor local ou pelo header X-MCP-Lockdown no remoto: ele filtra conteúdo de autores sem acesso de push ao repositório, como contenção contra injeção de prompt vinda de fora

Só que atenção: ele não é barreira de autorização

Não muda o que a credencial consegue ler ou escrever, o conteúdo filtrado ainda pode ser alcançado por outras ferramentas ou pela API com a mesma credencial, e repositório privado não é afetado

A segunda camada é a sanitização: o GitHub MCP filtra caracteres Unicode invisíveis no texto de issues e pull requests, aqueles que poderiam esconder instrução maliciosa no meio de um comentário aparentemente inofensivo

Próximo passo, bem prático: conecta hoje em modo somente leitura e passa alguns dias observando quais ferramentas a sua rotina realmente pede

Depois disso você libera escrita com dado na mão, não por precaução

E se o plano é levar isso pro time inteiro, vale o mesmo raciocínio de começar com um piloto pequeno antes de espalhar

até o próximo post! 🙂