Configuração do agente de codificação Pi 1.0: guia de instalação e MCP

Pi 1.0 é a primeira versão estável do Pi, um agente de codificação de terminal de código aberto da Earendil. Ele foi enviado em 1º de outubro de 2026 e este guia de configuração do agente de codificação Pi 1.0 leva você desde a instalação até um primeiro servidor MCP e um primeiro script de modo de código. Cada comando abaixo vem do documentação oficial do Pi.

Como configurar o Pi 1.0 e configurar servidores MCP

1. Instalar Pi com npm install -g --ignore-scripts @earendil-works/pi-coding-agent (Node.js 22.19 ou mais recente) ou o pi.dev script do instalador.
2. Verificar a instalação com pi --versionentão comece pi em uma pasta do projeto.
3. Conecte-se para um fornecedor modelo com /login.
4. Adicionar um servidor MCP com pi mcp add e verifique com pi mcp list.
5. Recarregar com /reload e deixe o modelo chamar o servidor de um codemode roteiro.

Índice

A versão 1.0 alterou alguns padrões e adicionou recursos importantes para este guia. De acordo com o registro de alteraçõesa UI do terminal agora roda em tela cheia por padrão (definir tuiMode para "regular" para manter a rolagem normal), o codemode usa cerca de 40% menos tokens de prompt e o manuseio do MCP OAuth foi reforçado.

Pi não é o chatbot Pi do Inflection AI. O agente de codificação mora em pi.dev e no earendil-works/pi repositório no GitHub.

npm install -g --ignore-scripts @earendil-works/pi-coding-agent
pi --version

curl -fsSL https://pi.dev/install.sh -o install.sh
less install.sh
sh install.sh

cd /path/to/project
pi

Pi precisa de acesso a um modelo por meio de um provedor. Dentro do Pi, corra /loginescolha um provedor e siga as instruções para usar uma assinatura ou armazenar uma chave de API. Correr /model depois para escolher um modelo diferente. O documentação de modelos abrange autenticação de variável de ambiente, modelos locais e endpoints personalizados.

Pi se conecta a Protocolo de Contexto do Modelo servidores sobre stdio ou HTTP streamable. Adicione um servidor stdio local, verifique a conexão e inicie o Pi:

pi mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem .
pi mcp list
pi

Tudo depois -- é o comando do servidor e seus argumentos. pi mcp add apenas grava a configuração e não conecta. pi mcp list conecta-se a todos os servidores habilitados e imprime seu estado, ferramentas e erros. Ele sai com status 1 quando uma entrada é inválida ou um servidor habilitado não está conectado, então você pode usá-lo em scripts.

Para um servidor remoto, passe uma URL e, se precisar de um token, o nome de uma variável de ambiente que o contém:

pi mcp add docs --url https://example.com/mcp --bearer-token-env-var DOCS_TOKEN
pi mcp list

Onde reside a configuração

Por padrão, os comandos gravam servidores em nível de usuário para ~/.pi/agent/mcp.json. Adicionar --local (ou -l) para gravar o arquivo do projeto .pi/mcp.json em vez de. Pi lê os servidores do projeto somente depois que você confia no projeto. Uma entrada de projeto substitui uma entrada de nível de usuário com o mesmo nome. O formato do arquivo corresponde a outros clientes MCP:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ("-y", "@modelcontextprotocol/server-filesystem", ".")
    },
    "docs": {
      "url": "https://example.com/mcp",
      "headers": { "Authorization": "Bearer ${DOCS_TOKEN}" },
      "description": "Search and read the product documentation"
    }
  }
}

Valores em env e headers pode fazer referência a variáveis ​​de ambiente como ${DOCS_TOKEN}então você não precisa armazenar um segredo no arquivo. Mantenha os servidores com credenciais no arquivo de nível de usuário e use o arquivo de projeto somente para os servidores exigidos pelo projeto. Depois de alterar um servidor fora de uma sessão, execute /reload dentro de Pi. Usar /mcp para inspecionar conexões, entrar, reconectar ou desabilitar um servidor.

Servidores que usam OAuth

Servidores remotos que usam OAuth não precisam de credenciais no mcp.json. Quando o servidor rejeitar uma conexão não autenticada, execute pi mcp login ou /mcp login . Pi abre a página de autorização, armazena tokens em ~/.pi/agent/mcp-auth.jsone os atualiza quando expiram. pi mcp logout exclui as credenciais armazenadas.

{
  "defaultTools": ("+codemode")
}

{
  "mcpServers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "exposure": "deferred",
      "toolExposure": {
        "search_code": "direct",
        "delete_*": "hidden"
      }
    }
  }
}

Pi mostra cada arquivo lido, pesquisa, comando e edição que ele faz, mas não pergunta antes de cada chamada de ferramenta. Revise as alterações quando terminar e use o controle de versão para trabalhos importantes. Para trabalhos não confiáveis ​​ou autônomos, execute Pi em um contêiner ou outra sandbox. O documentação de segurança explica a confiança do projeto e o que Pi pode acessar.

• Um servidor está ausente ou falhando: correr pi mcp list. /mcp dentro de uma sessão mostra o erro de conexão completo e o final do stderr de um servidor stdio com falha.
• As alterações de configuração não aparecem: correr /reload depois de adicionar, remover ou editar um servidor fora da sessão.
• Um servidor de projeto é ignorado: projeto .pi/mcp.json os arquivos são somente leitura para projetos confiáveis.
• Registros do servidor: notificações de registro são anexadas a ~/.pi/agent/mcp.log.
• Entradas inválidas: Pi os reporta e os ignora sem bloquear outros servidores. Os nomes dos servidores podem conter apenas letras, dígitos, _e -.

A partir daqui, adicione mais servidores MCPescreva um AGENTS.md com instruções que Pi deve seguir em uma pasta ou experimente habilidades e modelos de prompt. Navegue pelo site oficial Repositório de servidores MCP para servidores prontos e verifique o README de cada um antes de conceder acesso aos seus arquivos ou contas.