Servidor MCP do GitLab — Conecte assistentes de IA aos seus repositórios

Assistentes de IA podem escrever código, explicar um repositório e preparar alterações.

Mas sem acesso à sua instância do GitLab, eles só sabem o que você cola na conversa.

Isso rapidamente cria alguns problemas:

• o contexto do repositório se torna desatualizado;
• copiar arquivos manualmente é lento;
• operações de escrita precisam de permissões rigorosas;
• compartilhar um token completo do GitLab com cada cliente não é uma boa ideia.

Então eu construí GitLab MCP Server.

É um servidor Model Context Protocol sem estado escrito com Symfony. Ele permite que o ChatGPT e outros clientes MCP trabalhem com GitLab.com ou uma instância do GitLab auto-hospedada.

O que ele pode fazer?

O servidor expõe operações do GitLab como ferramentas MCP.

As ferramentas de leitura podem:

• listar e inspecionar projetos;
• navegar em uma árvore de repositório;
• ler arquivos;
• listar branches.

As ferramentas de escrita podem:

• criar ou atualizar um projeto;
• arquivar ou desarquivar um projeto;
• criar uma branch;
• criar ou atualizar arquivos;
• aplicar até 100 alterações de arquivos em um único commit atômico.

As ferramentas destrutivas são isoladas das ferramentas normais de escrita. Deletar um arquivo ou um projeto requer uma permissão adicional e deve ser explicitamente habilitado.

Segurança em primeiro lugar

Dar a um cliente de IA acesso ao código-fonte requer mais do que colocar um token do GitLab em uma variável de ambiente.

O servidor separa permissões em três escopos:

gitlab.read
gitlab.write
gitlab.destructive

Uma operação de escrita requer tanto gitlab.read quanto gitlab.write. Uma operação destrutiva também requer gitlab.destructive.

O modo de autenticação em produção usa OAuth 2.1. O provedor de identidade lida com o Código de Autorização com PKCE, enquanto o servidor MCP valida tokens de acesso localmente com o JWKS do provedor.

Ele verifica:

• a assinatura e o algoritmo do JWT;
• emissor e público;
• datas de expiração e ativação;
• assunto autenticado;
• escopos necessários.

O servidor também fornece:

• listas de permissão de projeto e namespace;
• validação de origem;
• limitação de taxa por sujeito autenticado;
• sanitização de resposta;
• interruptores separados para ferramentas de leitura, escrita e destrutivas.

A autenticação estática por bearer ainda está disponível para desenvolvimento local e migração, mas o OAuth é o modo recomendado para uma aplicação publicada.

Transporte MCP sem estado

O GitLab MCP Server implementa HTTP Streamable:

POST /mcp

Mensagens JSON-RPC usam POST /mcp.

O servidor também aceita GET /mcp como um stream leve de Server-Sent Events para negociação MCP e keep-alive. Nenhuma sessão de aplicação é armazenada no servidor.

A descoberta do protocolo permanece pública, então um cliente pode chamar:

• initialize;
• ping;
• tools/list.

Todo pedido de tools/call é autenticado antes que o GitLab seja contatado.

Os metadados de recurso protegido por OAuth são publicados em:

/.well-known/oauth-protected-resource
/.well-known/oauth-protected-resource/mcp

Isso permite que clientes compatíveis descubram o servidor de autorização e os escopos necessários.

Instalação

O projeto requer PHP 8.2 ou mais recente e Symfony 7.4 LTS.

Clone o repositório:

git clone https://git.small-project.dev/pub/apps/gitlab-mcp-symfony.git
cd gitlab-mcp-symfony
cp .env .env.local

Para um teste local, configure um token MCP estático e seu token de acesso do GitLab:

MCP_PUBLIC_URL=http://localhost:8080/mcp
MCP_AUTH_MODE=static
MCP_AUTH_TOKEN=replace-with-a-long-random-secret

GITLAB_URL=https://gitlab.example.com
GITLAB_TOKEN=glpat-xxxxxxxx
GITLAB_READ_ENABLED=true
GITLAB_WRITE_ENABLED=false
GITLAB_DESTRUCTIVE_ENABLED=false

Então inicie-o com Docker:

docker compose up -d --build

O endpoint MCP agora está disponível em:

http://127.0.0.1:8080/mcp

Mantenha as operações de escrita e destrutivas desativadas até que a conexão somente leitura esteja funcionando.

Configuração do OAuth

Em produção, configure o servidor como um servidor de recursos OAuth:

MCP_AUTH_MODE=oauth
MCP_OAUTH_RESOURCE=https://mcp.example.com/mcp
MCP_OAUTH_ISSUER=https://auth.example.com/realms/example
MCP_OAUTH_JWKS_URI=https://auth.example.com/realms/example/protocol/openid-connect/certs

MCP_OAUTH_READ_SCOPE=gitlab.read
MCP_OAUTH_WRITE_SCOPE=gitlab.write
MCP_OAUTH_DESTRUCTIVE_SCOPE=gitlab.destructive

Keycloak, Auth0, Okta, Cognito ou outro provedor compatível de OAuth/OIDC pode emitir o token de acesso.

O escopo OIDC openid é automaticamente anunciado com as permissões do GitLab. O valor do recurso deve corresponder exatamente ao público, ou à reivindicação de recurso, incluída no token de acesso.

Implantação

O repositório contém:

• uma imagem de produção do FrankenPHP;
• uma configuração do Docker Compose;
• testes unitários e funcionais;
• verificações do PHPStan;
• um pipeline do GitLab CI;
• scripts de implantação do Kubernetes.

Endpoints de saúde também estão disponíveis:

GET /healthz
GET /readyz

/healthz verifica o processo da aplicação. /readyz verifica a conexão com o GitLab e, no modo OAuth, o acesso ao endpoint JWKS.

Por que Symfony?

Symfony já fornece um sólido manuseio de HTTP, injeção de dependência, configuração, registro e ferramentas de teste.

Para um servidor MCP exposto na Internet, essas fundações são mais úteis do que construir um novo framework em torno do protocolo.

A aplicação permanece pequena, mas as partes de segurança e implantação permanecem explícitas e testáveis.

Código aberto

O GitLab MCP Server é lançado sob a licença GNU GPL v3.

Código fonte e documentação:

https://git.small-project.dev/pub/apps/gitlab-mcp-symfony

O projeto ainda está evoluindo. Feedback, relatórios de bugs e contribuições são bem-vindos.

Qual operação do GitLab você gostaria de expor a seguir?