Autenticação

Código Aberto — O GitScrum MCP Server é código aberto sob a licença MIT. Disponível no npm e no GitHub. Servidor Model Context Protocol para GitScrum — Claude, GitHub Copilot, Cursor e qualquer cliente compatível com MCP têm acesso operacional completo à sua stack de gerenciamento de projetos.

O GitScrum MCP Server usa OAuth 2.0 Device Authorization Grant (RFC 8628) para autenticação. Este é o mesmo fluxo usado por smart TVs e ferramentas CLI — você aprova o acesso no seu navegador, e o servidor MCP recebe um token sem nunca ver sua senha.

Esta abordagem foi escolhida especificamente para MCP porque assistentes de IA nunca devem manipular credenciais de usuário diretamente. A aprovação via navegador garante que sua senha fica entre você e o GitScrum.

Como o Device Authorization Funciona

O OAuth 2.0 Device Authorization Grant é projetado para dispositivos e aplicações que não podem abrir um navegador diretamente. No contexto MCP, o "dispositivo" é o servidor MCP rodando como um processo local, e a aprovação no navegador acontece na sua máquina.

Por que este fluxo para MCP

Fluxos OAuth tradicionais requerem uma URI de redirecionamento — o serviço redireciona o navegador de volta para a aplicação após o login. Servidores MCP se comunicam via stdio (entrada/saída padrão) e não têm um servidor web para receber redirecionamentos. O Device Authorization Grant resolve isso desacoplando o dispositivo de login (seu navegador) do dispositivo da aplicação (o servidor MCP).

Propriedades de segurança principais:

• Sua senha é digitada apenas no navegador, na página de login do GitScrum
• O servidor MCP nunca vê, armazena ou transmite suas credenciais
• O assistente de IA recebe apenas um token de acesso com escopo definido
• As permissões do token correspondem ao papel da sua conta GitScrum

Fluxo de Autenticação

O fluxo completo de autenticação envolve quatro ferramentas e dois atores: o assistente de IA (que chama ferramentas MCP) e você (que aprova no navegador).

Etapa 1: Iniciar login

Diga ao seu assistente de IA para fazer login no GitScrum. O assistente chama a ferramenta auth_login.

Você:  "Fazer login no GitScrum"
IA:    Chama a ferramenta auth_login

O servidor MCP entra em contato com o servidor de autorização do GitScrum e recebe:

• Uma URL de verificação onde você aprovará o acesso
• Um código de usuário que identifica esta solicitação específica de login
• Um tempo de expiração para o código (tipicamente 15 minutos)

O assistente de IA exibe esta informação para você:

Abra esta URL no seu navegador: https://gitscrum.com/device
Digite este código: ABCD-1234
O código expira em 15 minutos.

Etapa 2: Aprovação no navegador

Abra a URL de verificação em qualquer navegador em qualquer dispositivo. Você verá uma página pedindo o código de usuário.

1. Digite o código de usuário exatamente como mostrado (incluindo o hífen)
2. Faça login na sua conta GitScrum se ainda não estiver logado
3. Revise as permissões solicitadas pelo servidor MCP
4. Clique em Aprovar para autorizar o acesso

Após a aprovação, o navegador mostra uma página de confirmação. Você pode fechar a aba do navegador.

Etapa 3: Completar autenticação

Diga ao seu assistente de IA que você aprovou o acesso:

Você:  "Aprovei o acesso" ou "Completar o login do GitScrum"
IA:    Chama a ferramenta auth_complete

O servidor MCP troca o código de dispositivo por um token de acesso e um token de atualização. Ambos são armazenados localmente na sua máquina.

Etapa 4: Sessão ativa

O assistente de IA confirma que a sessão está ativa:

IA:   "Você está autenticado como john@acme.com. Você tem acesso a 3 workspaces."

A partir deste ponto, todas as chamadas de ferramentas MCP são autenticadas automaticamente. Você não precisará fazer login novamente nesta sessão.

Gerenciamento de Tokens

Armazenamento de tokens

Após autenticação bem-sucedida, os tokens são armazenados localmente em:

~/.gitscrum/auth.json

• macOS/Linux: /Users/seuusuario/.gitscrum/auth.json
• Windows: C:\Users\seuusuario\.gitscrum\auth.json

O arquivo contém o token de acesso e o token de atualização. Ele é criado com permissões de arquivo restritas (legível apenas pelo usuário atual).

Atualização automática

Tokens de acesso expiram após um período definido. Quando um token expira, o servidor MCP usa automaticamente o token de atualização para obter um novo token de acesso — nenhuma interação do usuário é necessária.

Isso acontece de forma transparente. Você não verá prompts de autenticação durante o uso normal. O ciclo de atualização continua até que o próprio token de atualização expire ou você faça logout explicitamente.

Persistência de sessão

Sua autenticação persiste entre reinicializações do servidor MCP. Quando você reinicia seu cliente de IA (Claude Desktop, VS Code, Cursor), o servidor MCP lê o token armazenado de ~/.gitscrum/auth.json e retoma a sessão automaticamente.

Isso significa que você autentica uma vez e permanece logado enquanto o token de atualização for válido.

Ferramentas de Autenticação

auth_login

Inicia o fluxo de Device Authorization Grant.

Quando usar: Configuração inicial, ou após fazer logout.

O que retorna:

• verification_url — URL para abrir no seu navegador
• user_code — Código para digitar na página de verificação
• expires_in — Segundos até o código expirar

Exemplo de interação:

Você:  "Fazer login no GitScrum"
IA:    "Abra https://gitscrum.com/device e digite o código ABCD-1234.
        O código expira em 15 minutos."

auth_complete

Completa o fluxo de autenticação após aprovação no navegador.

Quando usar: Após você ter digitado o código e aprovado o acesso no navegador.

O que retorna:

• Status de autenticação (sucesso ou pendente)
• Informações do usuário (nome, e-mail)
• Workspaces acessíveis

Exemplo de interação:

Você:  "Aprovei"
IA:    "Autenticado como john@acme.com. 3 workspaces disponíveis."

Se a aprovação no navegador ainda não aconteceu, auth_complete retorna um status "pendente" e o assistente de IA informará você.

auth_status

Verifica o estado atual da autenticação sem iniciar um login.

Quando usar: Sempre que quiser verificar se sua sessão está ativa.

O que retorna:

• Se uma sessão válida existe
• Detalhes do usuário autenticado
• Status de validade do token

Exemplo de interação:

Você:  "Estou logado no GitScrum?"
IA:    "Sim, autenticado como john@acme.com. Sessão ativa."

auth_logout

Limpa todos os tokens de autenticação armazenados.

Quando usar: Ao trocar de conta, compartilhar uma máquina ou encerrar uma sessão.

O que faz:

• Exclui o arquivo de token local (~/.gitscrum/auth.json)
• Limpa qualquer estado de token em memória
• A próxima chamada MCP que exigir autenticação disparará um novo fluxo de login

Exemplo de interação:

Você:  "Sair do GitScrum"
IA:    "Logout realizado. Tokens limpos."

Considerações de Segurança

Credenciais nunca alcançam a IA

O Device Authorization Grant impede especificamente que o assistente de IA acesse suas credenciais. Veja o que cada ator vê:

O assistente de IA sabe que a autenticação foi bem-sucedida e a quais workspaces você tem acesso, mas nunca manipula tokens diretamente. Os tokens existem apenas no processo do servidor MCP e no arquivo de armazenamento local.

Armazenamento apenas local

Os tokens são armazenados exclusivamente no sistema de arquivos local em ~/.gitscrum/auth.json. Eles nunca são:

• Enviados para provedores de modelos de IA (Anthropic, OpenAI, etc.)
• Registrados no console ou saída
• Incluídos no contexto de conversa da IA
• Transmitidos para terceiros

Escopo do token

O token de acesso herda as permissões da sua conta GitScrum. Se sua conta tem acesso somente leitura a certos projetos, o servidor MCP tem as mesmas restrições. O servidor MCP não solicita permissões elevadas além do que sua conta já possui.

Rate limiting na autenticação

Para prevenir ataques de força bruta, o endpoint de autenticação aplica rate limiting:

• Múltiplas tentativas falhas de código de dispositivo disparam bloqueio automático
• A duração do bloqueio aumenta com falhas repetidas
• Autenticação bem-sucedida reseta o contador

Uso com Múltiplas Contas

Trocar de conta

Para trocar para uma conta GitScrum diferente:

1. Diga ao seu assistente de IA para sair: "Sair do GitScrum"
2. Os tokens armazenados são limpos
3. Diga ao seu assistente de IA para fazer login: "Fazer login no GitScrum"
4. Complete o fluxo no navegador com a nova conta

Máquinas compartilhadas

Em máquinas compartilhadas, sempre faça logout quando terminar. A ferramenta authlogout limpa o arquivo de token local completamente. Verifique com authstatus que nenhuma sessão permanece ativa.

Solução de Problemas

Erro "Code expired"

Os códigos de dispositivo expiram após 15 minutos. Se você vir este erro:

1. Peça ao assistente de IA para executar auth_login novamente
2. Um novo código é gerado
3. Complete o fluxo no navegador rapidamente

"Authorization pending" após aprovação

Se auth_complete retorna "pendente" mesmo após você ter aprovado no navegador:

• Verifique se digitou o código correto (confira erros de digitação)
• Certifique-se de que clicou no botão Aprovar na página de confirmação
• Aguarde alguns segundos e tente auth_complete novamente — pode haver um breve atraso na propagação

Erros "Unauthorized" durante o uso

Se você vir erros 401 durante operação normal:

• O token de acesso pode ter expirado e a atualização automática falhou
• Execute authlogout seguido de authlogin para reautenticar
• Verifique se sua conta GitScrum ainda está ativa

Permissões do arquivo de token

Se a autenticação tem sucesso mas as requisições subsequentes falham, verifique as permissões do arquivo de token:

# macOS/Linux
ls -la ~/.gitscrum/auth.json

# Windows (PowerShell)
Get-Acl "$env:USERPROFILE\.gitscrum\auth.json"

O arquivo deve ser legível apenas pela sua conta de usuário. Se as permissões forem muito restritivas (não legível por você) ou muito permissivas (legível por outros), ajuste conforme necessário.

O navegador não abre automaticamente

O servidor MCP exibe a URL para você abrir manualmente. Ele não tenta abrir seu navegador. Copie a URL e cole-a em qualquer navegador.

Substituição por Variável de Ambiente

Para ambientes CI/CD ou automatizados onde a aprovação via navegador não é prática, você pode contornar o fluxo Device Grant definindo um token diretamente:

export GITSCRUM_TOKEN=seu-token-de-api

Quando GITSCRUM_TOKEN está definido, o servidor MCP o usa diretamente em vez do arquivo de token armazenado. Isto é destinado a cenários de desenvolvimento e automação — não para uso interativo regular.

Nota de segurança: Certifique-se de que o ambiente onde GITSCRUM_TOKEN está definido é seguro. Variáveis de ambiente podem ser visíveis para outros processos na mesma máquina.

Próximos Passos

• Segurança: Modelo de segurança completo incluindo HTTPS, rate limiting e tratamento de erros.
• Configuração: Configuração específica por cliente para Claude Desktop, GitHub Copilot, Cursor e mais.
• Início Rápido: Tutorial completo de configuração se você ainda não instalou.
• Visão Geral do MCP: Todas as 29 ferramentas e mais de 160 operações disponíveis após autenticação.