Como Conectar o GitHub Copilot no IntelliJ ao Notion via MCP

Por que Conectar o Notion ao seu IDE?

Imagine seu assistente de código IA podendo ler a documentação do seu projeto, atualizar rastreadores de issues e criar notas de reunião — tudo sem sair do seu IDE. É exatamente isso que o Model Context Protocol (MCP) possibilita.

O MCP é um padrão aberto que permite que assistentes de IA interajam com ferramentas e serviços externos. Embora este tutorial use o GitHub Copilot, a mesma abordagem funciona com qualquer IA compatível com MCP — incluindo ChatGPT, Claude, Google Gemini e outros.

Por que GitHub Copilot?

Escolhemos o GitHub Copilot para este guia por causa da realidade em muitas empresas alemãs: ferramentas de IA frequentemente são restritas por políticas corporativas, e quando são permitidas, o GitHub Copilot Enterprise com regras de acesso personalizadas é tipicamente a opção aprovada. Como o Copilot é permitido na maioria dos nossos projetos, queríamos uma forma de documentar automaticamente nossas alterações diretamente do IDE.

Por que Notion?

Da mesma forma, ferramentas enterprise como Confluence frequentemente estão bloqueadas — desenvolvedores podem não ter acesso via API ou MCP devido a políticas de TI. Nossa solução: criar documentação no Notion (que oferece excelente acesso via API), e depois transferir manualmente o conteúdo para o Confluence quando necessário. Isso nos dá os benefícios da automação enquanto permanecemos em conformidade.

Ao conectar o Notion via MCP, você dá ao seu assistente de IA a capacidade de:

• Ler documentação – Acessar specs do projeto, docs de API e base de conhecimento
• Atualizar issues – Documentar bugs, criar relatórios de correção e acompanhar progresso
• Criar conteúdo – Gerar notas de reunião, documentação técnica e mais

Neste tutorial, vamos percorrer o processo completo de configuração.

Pré-requisitos

Antes de começar, certifique-se de ter:

• IntelliJ IDEA (2024.1 ou posterior com plugin do GitHub Copilot)
• Uma conta do Notion com acesso de administrador ao workspace
• Node.js instalado (para executar o servidor MCP)
• Assinatura do GitHub Copilot com recursos de chat habilitados

Passo 1: Criar uma Integração no Notion

Primeiro, precisamos criar uma integração interna no Notion para gerar um token de API. Este token permite que o servidor MCP se autentique com seu workspace.

Navegar até Integrações

Faça login no Notion e vá para Configurações → Conexões. Na parte inferior da página, clique em "Desenvolver ou gerenciar integrações". Isso abre o portal de integrações do Notion em uma nova aba.

Criar uma Nova Integração

Na página de integrações, clique em "+ Nova integração".

Configure sua integração:

1. Dê um nome descritivo (ex: "IntelliJ Copilot")
2. Selecione o workspace que deseja conectar
3. Vá para a aba Capacidades
4. Habilite as permissões que sua IA precisa (veja abaixo)
5. Clique em Salvar alterações

Permissões necessárias:

• Ler conteúdo – Necessário para ler páginas e bancos de dados
• Atualizar conteúdo – Necessário para editar conteúdo existente
• Inserir conteúdo – Necessário para criar novo conteúdo

Após salvar, copie seu Segredo da Integração Interna (começa com ntn_). Mantenha este token seguro — trate-o como uma senha.

Conceder Acesso às Páginas

Por padrão, sua integração não pode acessar nenhuma página. Você precisa conceder acesso explicitamente às páginas que deseja que a IA trabalhe.

Volte para Configurações → Conexões no Notion. Encontre sua integração na lista e clique no menu "...". Selecione "Gerenciar acesso às páginas" e escolha quais páginas de nível superior a integração deve ter acesso.

Dica: Comece com um workspace ou pasta de projeto específico em vez de conceder acesso a tudo. Você sempre pode expandir o acesso depois.

Passo 2: Configurar MCP no IntelliJ

Agora vamos configurar o IntelliJ para usar o servidor MCP do Notion. A abordagem mais fácil é usar o pacote oficial do servidor MCP do Notion.

Abrir Configurações do MCP

No IntelliJ IDEA:

1. Abra Settings (ou Preferences no macOS)
2. Navegue até Tools → GitHub Copilot → Model Context Protocol
3. Clique em Configure

Isso abre o arquivo de configuração mcp.json.

Adicionar o Servidor do Notion

Adicione a seguinte configuração ao seu arquivo mcp.json:

{\n  "servers": {\n    "notion": {\n      "command": "npx",\n      "args": ["-y", "@notionhq/notion-mcp-server"],\n      "env": {\n        "NOTION_TOKEN": "ntn_seu_token_aqui"\n      }\n    }\n  }\n}

Substitua ntn_seu_token_aqui pelo token de integração que você copiou anteriormente.

Verificar a Conexão

Após salvar a configuração:

1. Abra o painel GitHub Copilot Chat
2. Selecione o modo Agent no dropdown
3. Clique no ícone de ferramentas (ícone de chave/configurações)
4. Procure por "notion" na lista de ferramentas disponíveis

Se você vir as ferramentas da API do Notion listadas (como API-get-user, API-post-search, etc.), parabéns — você está conectado!

Passo 3: Testar a Integração

Vamos verificar se tudo funciona com um exemplo prático. Vamos pedir para a IA criar documentação no Notion baseada em um template.

Criar um Template (Opcional)

Para documentação consistente, crie uma página de template no Notion que a IA possa referenciar. Por exemplo, um template de rastreamento de issues:

Nota: Templates ajudam a guiar a IA, mas não espere 100% de aderência perfeita. A IA captura a estrutura geral e o estilo, o que geralmente é suficiente para uso prático. Você pode precisar fazer pequenos ajustes depois.

Testar com um Prompt

No chat do Copilot, tente um prompt como este:

Para uma demo de documentação, quero que você crie \num relatório de issue de exemplo no Notion.\n\nPágina destino: [URL da sua página do Notion]\nReferência de template: [URL do seu template]\n\nUse o mesmo estilo e layout do template, \ne tenha cuidado com a formatação correta do Notion.

A IA usará as ferramentas do Notion para ler o template, entender sua estrutura e criar um novo documento formatado corretamente.

Casos de Uso Práticos

Uma vez conectado, aqui estão algumas formas poderosas de usar esta integração:

Documentação de Desenvolvimento

• Relatórios de bugs – "Documente este bug que acabei de corrigir no nosso banco de issues"
• Code reviews – "Resuma as alterações neste PR e adicione ao nosso changelog"
• Docs de API – "Gere documentação para este endpoint e adicione à nossa referência de API"

Gerenciamento de Projetos

• Notas de reunião – "Crie um resumo de reunião a partir destes pontos de discussão"
• Rastreamento de tarefas – "Atualize o status da tarefa X no nosso board de sprint"
• Base de conhecimento – "Adicione esta solução ao nosso guia de troubleshooting"

Pesquisa & Aprendizado

• Ler contexto – "Resuma nossa arquitetura de autenticação a partir dos docs"
• Encontrar informações – "Pesquise nossa base de conhecimento por estratégias de cache"

Solução de Problemas

Ferramentas Não Aparecem

Se as ferramentas do Notion não aparecerem na lista de ferramentas:

• Verifique se seu token está formatado corretamente (começa com ntn_)
• Confirme que o Node.js está instalado e acessível
• Reinicie o IntelliJ após salvar a configuração
• Procure por mensagens de erro no log de eventos do IntelliJ

Erros de Permissão

Se a IA não conseguir acessar certas páginas:

• Verifique se você concedeu acesso às páginas através das configurações de Conexões
• Confirme que a integração tem as capacidades necessárias habilitadas
• Lembre-se que o acesso é herdado — conceder acesso a uma página pai inclui páginas filhas

Problemas de Conexão

Se o servidor falhar ao iniciar:

• Tente executar npx @notionhq/notion-mcp-server manualmente em um terminal para ver mensagens de erro
• Certifique-se de ter uma conexão de internet estável
• Verifique se seu firewall está bloqueando a conexão

Conclusão

Conectar o Notion ao seu IDE através do MCP abre possibilidades poderosas para documentação assistida por IA e gerenciamento de projetos. Seu assistente de código agora tem contexto sobre a estrutura do seu projeto, pode atualizar sua documentação em tempo real e ajuda a manter consistência em toda sua base de conhecimento.

A configuração leva apenas alguns minutos, mas os ganhos de produtividade se acumulam com o tempo. Comece com um caso de uso focado — como documentar bugs ou atualizar um changelog — e expanda a partir daí conforme descobrir novos fluxos de trabalho.