Configura el servidor MCP de PandaNpc para Claude Code y Codex

Actualizado

El servidor MCP de PandaNpc conecta un agente de codificación compatible con MCP a tu base de conocimiento de PandaNote, registros de trabajo, tareas programadas, configuración de modelos y Centro de Servicio de Agentes. Es útil cuando un agente necesita contexto de proyecto duradero en lugar de comenzar desde una conversación vacía cada vez.

El servidor se ejecuta localmente mediante el transporte estándar de entrada/salida de MCP. Tu cliente MCP inicia el proceso pandanpc-mcp cuando se abre una sesión; no necesitas exponer un puerto ni ejecutar un servidor web separado.

Antes de instalar

Necesitas:

  • Node.js y npm disponibles en el mismo entorno donde se ejecuta el cliente MCP.
  • Una cuenta de PandaNpc con acceso a la dirección de correo electrónico utilizada para la verificación.
  • Claude Code, OpenAI Codex, Cursor u otro cliente que admita servidores MCP stdio locales.

Si quieres que el agente programe trabajo en uno de tus propios ordenadores, instala y conecta PandaPaw primero. Las herramientas de notas y espacios de trabajo no requieren un dispositivo PandaPaw en línea.

Instalar o actualizar el servidor MCP

Instala el paquete globalmente en macOS, Linux o Windows:

bash
npm install -g @pandanpc/mcp-server

Confirma que el ejecutable es visible para tu shell:

bash
pandanpc-mcp --help

Ejecuta el mismo comando npm cada vez que quieras actualizar. Reinicia el cliente MCP después de una actualización porque un cliente ya en ejecución mantiene la versión del proceso que lanzó originalmente.

Consulta el historial de versiones del servidor MCP cuando una herramienta o su comportamiento difiera de una captura de pantalla o tutorial anterior.

Añadir PandaNpc a Claude Code

El método más fiable es el comando de configuración propio de Claude Code. Usa el ámbito de usuario si quieres que PandaNpc esté disponible en todos los proyectos:

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

Usa --scope project en su lugar cuando la configuración deba compartirse a través del repositorio actual, o --scope local cuando deba aplicarse solo a ti en el proyecto actual.

Comprueba el servidor registrado:

bash
claude mcp get pandanpc
claude mcp list

También puedes configurar el servidor stdio manualmente en la configuración MCP utilizada por tu instalación de Claude Code:

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

Añadir PandaNpc a OpenAI Codex

Codex puede registrar el mismo proceso local desde la línea de comandos:

bash
codex mcp add pandanpc -- pandanpc-mcp

Verifica la configuración guardada:

bash
codex mcp get pandanpc
codex mcp list

La entrada equivalente en ~/.codex/config.toml es:

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

Reinicia Codex o abre una nueva sesión después de añadir el servidor. Si mantienes un archivo de configuración personalizado de Codex, coloca la tabla MCP en ese archivo en lugar de duplicarla en varios archivos.

Configurar Cursor y otros clientes MCP

Para Cursor, añade un servidor local a ~/.cursor/mcp.json usando la misma forma JSON mostrada para Claude Code. Para Windsurf y otros clientes, crea un servidor MCP stdio cuyo comando sea pandanpc-mcp y cuya lista de argumentos esté vacía.

El ejecutable debe estar en el PATH heredado por la aplicación gráfica. Si funciona en una terminal pero el cliente de escritorio informa «comando no encontrado», usa la ruta absoluta del ejecutable devuelta por el siguiente comando:

bash
command -v pandanpc-mcp

En Windows PowerShell, usa:

powershell
Get-Command pandanpc-mcp

Iniciar sesión desde el agente

PandaNpc utiliza un flujo de verificación de correo electrónico en dos pasos. Pide al agente que realice estas acciones en orden:

  1. Llama a note_login con tu dirección de correo electrónico. PandaNpc envía un código de verificación.
  2. Llama a note_login nuevamente con la misma dirección de correo electrónico y el código.

La credencial local se almacena en caché, por lo que no deberías necesitar iniciar sesión en cada sesión. Nunca pegues el código de verificación en una transcripción pública o en un prompt compartido.

Verificar la conexión MCP

Ejecuta una pequeña prueba de solo lectura antes de permitir que el agente cree o edite datos:

  1. Pídele que llame a list_workspaces.
  2. Pídele que llame a list_notes para un espacio de trabajo.
  3. Pídele que busque una palabra clave inofensiva con search_notes.

Una respuesta exitosa demuestra que el cliente MCP inició el proceso, la autenticación se completó y la API de la cuenta es accesible. Para una prueba de escritura, crea una nota desechable y luego elimínala de forma suave (soft-delete).

La lista exacta de herramientas mostrada por tu cliente MCP es la fuente de verdad para la versión instalada. Las herramientas se agrupan en estos flujos de trabajo:

Flujo de trabajo Herramientas típicas Comportamiento importante
Notas list_notes, create_note, read_note, update_note, search_notes update_note reemplaza el cuerpo completo; lee antes de editar
Registros de trabajo save_done Almacena el trabajo completado en la carpeta del proyecto de hoy automáticamente
Espacios de trabajo list_workspaces, create_workspace, update_workspace Una ruta de proyecto vinculada permite que el servidor encuentre el espacio de trabajo correcto
Trabajo programado list_scheduled_bridges, create_scheduled_task, list_scheduled_task_runs Una máquina PandaPaw debe estar en línea; las expresiones cron usan seis campos
Proveedores y modelos list_providers, list_models, herramientas de creación/actualización/eliminación Enumera primero para usar IDs actuales y tipos de modelo válidos
Reglas y habilidades sync_rules Sincroniza las instrucciones de proyecto admitidas omitiendo archivos sin cambios

Para las definiciones de campos de proveedores y modelos, consulta Proveedores de IA personalizados y API keys. Para los límites de cuenta y facturación, consulta Cuentas, planes y costos de API de PandaNpc.

Prácticas operativas seguras

  • Comienza con herramientas de listado, lectura o búsqueda antes de acciones de creación, actualización, eliminación o programación.
  • Lee una nota antes de actualizarla porque las actualizaciones de notas reemplazan todo el documento Markdown en lugar de aplicar un parche.
  • Trata los prompts programados como solicitudes de ejecución de código: confirma la máquina de destino, el directorio de trabajo, la zona horaria y la expresión cron de seis campos.
  • Mantén las API keys de los proveedores fuera de los prompts y las notas. Introduce los secretos solo a través del flujo de configuración del proveedor correspondiente.
  • Revisa la tarjeta de aprobación de herramientas MCP antes de permitir acciones destructivas o externas.
  • Usa save_done para los registros de trabajo en lugar de adivinar manualmente el espacio de trabajo y la carpeta de fecha correctos.

Solución de problemas

El cliente dice que no se encontró `pandanpc-mcp`

Abre una nueva terminal después de la instalación y verifica la ruta del ejecutable. Las aplicaciones de escritorio a veces heredan un PATH anterior; configura la ruta absoluta o reinicia la aplicación. Si npm se instaló mediante un administrador de versiones, asegúrate de que el cliente MCP se inicie con el mismo usuario y entorno.

El servidor está registrado pero no aparecen herramientas

Reinicia el cliente y luego inspecciona claude mcp get pandanpc o codex mcp get pandanpc. Elimina y vuelve a añadir la entrada si el comando es incorrecto. También verifica que no hayas configurado el proceso stdio local como una URL HTTP.

Las herramientas indican que no estás autenticado

Repite las dos llamadas a note_login. Usa el código de verificación más reciente, revisa la carpeta de spam y confirma que ambas llamadas usen la misma dirección de correo electrónico.

Las tareas programadas no pueden encontrar una máquina

Llama primero a list_scheduled_bridges. Si no devuelve ningún dispositivo disponible, verifica el estado de PandaPaw y la conectividad del dispositivo en la máquina de destino. Una máquina que está apagada, en reposo, con la sesión cerrada o desconectada no puede iniciar una ejecución programada.

Una actualización de nota eliminó texto existente

update_note acepta el cuerpo de reemplazo completo. Restaura la nota desde su historial o papelera si está disponible, luego lee el contenido actual y envía el documento combinado.

¿Necesitas ayuda específica de tu cuenta? Contacta con support@pandanpc.com e incluye el nombre del cliente MCP, el sistema operativo, la versión del paquete y el mensaje de error exacto sin secretos.