Configure o servidor MCP PandaNpc para Claude Code e Codex

Atualizado

O servidor MCP PandaNpc conecta um agente de codificação compatível com MCP à sua base de conhecimento do PandaNote, registros de trabalho, tarefas agendadas, configuração de modelos e Central de Serviços do Agente. É útil quando um agente precisa de contexto de projeto durável em vez de começar de uma conversa vazia toda vez.

O servidor é executado localmente pelo transporte de entrada/saída padrão do MCP. Seu cliente MCP inicia o processo pandanpc-mcp quando uma sessão é aberta; você não precisa expor uma porta ou executar um servidor web separado.

Antes de instalar

Você precisa:

  • Node.js e npm disponíveis no mesmo ambiente em que o cliente MCP é executado.
  • Uma conta PandaNpc com acesso ao endereço de e-mail usado para verificação.
  • Claude Code, OpenAI Codex, Cursor ou outro cliente que suporte servidores MCP stdio locais.

Se você quiser que o agente agende trabalho em um dos seus próprios computadores, instale e conecte PandaPaw primeiro. As ferramentas de notas e espaço de trabalho não exigem um dispositivo PandaPaw online.

Instalar ou atualizar o servidor MCP

Instale o pacote globalmente no macOS, Linux ou Windows:

bash
npm install -g @pandanpc/mcp-server

Confirme que o executável está visível para o seu shell:

bash
pandanpc-mcp --help

Execute o mesmo comando npm sempre que quiser atualizar. Reinicie o cliente MCP após uma atualização, pois um cliente já em execução mantém a versão do processo que foi iniciada originalmente.

Consulte o histórico de versões do servidor MCP quando uma ferramenta ou seu comportamento diferir de uma captura de tela ou tutorial mais antigo.

Adicionar PandaNpc ao Claude Code

O método mais confiável é o próprio comando de configuração do Claude Code. Use o escopo de usuário se quiser que o PandaNpc esteja disponível em todos os projetos:

bash
claude mcp add --scope user pandanpc -- pandanpc-mcp

Use --scope project quando a configuração deve ser compartilhada por meio do repositório atual, ou --scope local quando deve se aplicar apenas a você no projeto atual.

Verifique o servidor registrado:

bash
claude mcp get pandanpc
claude mcp list

Você também pode configurar o servidor stdio manualmente na configuração MCP usada pela sua instalação do Claude Code:

json
{
  "mcpServers": {
    "pandanpc": {
      "command": "pandanpc-mcp"
    }
  }
}

Adicionar PandaNpc ao OpenAI Codex

O Codex pode registrar o mesmo processo local pela linha de comando:

bash
codex mcp add pandanpc -- pandanpc-mcp

Verifique a configuração salva:

bash
codex mcp get pandanpc
codex mcp list

A entrada equivalente em ~/.codex/config.toml é:

toml
[mcp_servers.pandanpc]
command = "pandanpc-mcp"

Reinicie o Codex ou abra uma nova sessão após adicionar o servidor. Se você mantém um arquivo de configuração customizado do Codex, coloque a tabela MCP nesse arquivo em vez de duplicá-la em vários arquivos.

Configurar o Cursor e outros clientes MCP

Para o Cursor, adicione um servidor local a ~/.cursor/mcp.json usando o mesmo formato JSON mostrado para o Claude Code. Para Windsurf e outros clientes, crie um servidor MCP stdio cujo comando seja pandanpc-mcp e cuja lista de argumentos esteja vazia.

O executável deve estar no PATH herdado pelo aplicativo gráfico. Se funcionar em um terminal, mas o cliente desktop informar “comando não encontrado”, use o caminho absoluto do executável retornado pelo seguinte comando:

bash
command -v pandanpc-mcp

No Windows PowerShell, use:

powershell
Get-Command pandanpc-mcp

Fazer login por meio do agente

O PandaNpc usa um fluxo de verificação de e-mail em duas etapas. Peça ao agente para executar estas ações em ordem:

  1. Chame note_login com seu endereço de e-mail. O PandaNpc envia um código de verificação.
  2. Chame note_login novamente com o mesmo endereço de e-mail e o código.

A credencial local é armazenada em cache, portanto você não deve precisar entrar em todas as sessões. Nunca cole o código de verificação em uma transcrição pública ou em um prompt compartilhado.

Verificar a conexão MCP

Execute um pequeno teste somente leitura antes de permitir que o agente crie ou edite dados:

  1. Peça a ele para chamar list_workspaces.
  2. Peça a ele para chamar list_notes para um espaço de trabalho.
  3. Peça a ele para pesquisar uma palavra-chave inofensiva com search_notes.

Uma resposta bem-sucedida prova que o cliente MCP iniciou o processo, a autenticação foi concluída e a API da conta está acessível. Para um teste de escrita, crie uma nota descartável e depois exclua-a logicamente (soft-delete).

A lista exata de ferramentas exibida pelo seu cliente MCP é a fonte da verdade para a versão instalada. As ferramentas são agrupadas em torno destes fluxos de trabalho:

Fluxo de trabalho Ferramentas típicas Comportamento importante
Notas list_notes, create_note, read_note, update_note, search_notes update_note substitui o corpo completo; leia antes de editar
Registros de trabalho save_done Armazena o trabalho concluído na pasta do projeto de hoje automaticamente
Espaços de trabalho list_workspaces, create_workspace, update_workspace Um caminho de projeto vinculado permite que o servidor encontre o espaço de trabalho correto
Trabalho agendado list_scheduled_bridges, create_scheduled_task, list_scheduled_task_runs Uma máquina PandaPaw deve estar online; expressões cron usam seis campos
Provedores e modelos list_providers, list_models, ferramentas de criar/atualizar/excluir Liste primeiro para usar IDs atuais e tipos de modelo válidos
Regras e habilidades sync_rules Sincroniza instruções de projeto suportadas, ignorando arquivos inalterados

Para definições de campos de provedores e modelos, consulte Provedores de IA personalizados e API Keys. Para limites de conta e cobrança, consulte Contas, planos e custos de API do PandaNpc.

Práticas operacionais seguras

  • Comece com ferramentas de listar, ler ou pesquisar antes de ações de criar, atualizar, excluir ou agendar.
  • Leia uma nota antes de atualizá-la, pois as atualizações de nota substituem todo o documento Markdown em vez de aplicar um patch.
  • Trate prompts agendados como solicitações de execução de código: confirme a máquina de destino, o diretório de trabalho, o fuso horário e a expressão cron de seis campos.
  • Mantenha as API Keys de provedores fora de prompts e notas. Insira segredos apenas pelo fluxo de configuração do provedor pretendido.
  • Revise o cartão de aprovação de ferramentas MCP antes de permitir ações destrutivas ou externas.
  • Use save_done para registros de trabalho em vez de adivinhar manualmente o espaço de trabalho e a pasta de data corretos.

Solução de problemas

O cliente diz que `pandanpc-mcp` não foi encontrado

Abra um novo terminal após a instalação e verifique o caminho do executável. Aplicativos desktop às vezes herdam um PATH mais antigo; configure o caminho absoluto ou reinicie o aplicativo. Se o npm foi instalado por meio de um gerenciador de versão, certifique-se de que o cliente MCP inicie sob o mesmo usuário e ambiente.

O servidor está registrado, mas nenhuma ferramenta aparece

Reinicie o cliente e inspecione claude mcp get pandanpc ou codex mcp get pandanpc. Remova e adicione a entrada novamente se o comando estiver errado. Verifique também se você não configurou o processo stdio local como uma URL HTTP.

As ferramentas dizem que você não está autenticado

Repita as duas chamadas note_login. Use o código de verificação mais recente, verifique a pasta de spam e confirme que ambas as chamadas usam o mesmo endereço de e-mail.

Tarefas agendadas não conseguem encontrar uma máquina

Chame list_scheduled_bridges primeiro. Se ele não retornar nenhum dispositivo disponível, verifique o status do PandaPaw e a conectividade do dispositivo na máquina de destino. Uma máquina desligada, em repouso, com sessão encerrada ou desconectada não pode iniciar uma execução agendada.

Uma atualização de nota removeu texto existente

update_note aceita o corpo completo de substituição. Restaure a nota do histórico ou da lixeira, quando disponível, leia o conteúdo atual e envie o documento combinado.

Precisa de ajuda específica para sua conta? Entre em contato com support@pandanpc.com e inclua o nome do cliente MCP, sistema operacional, versão do pacote e a mensagem de erro exata, sem segredos.