Pickaxe AI Agent MCP

Servidor MCP Pickaxe

Un servidor MCP (Model Context Protocol) que conecta asistentes de IA como Claude con la plataforma Pickaxe. Gestiona tus agentes de IA, bases de conocimiento, usuarios y análisis directamente mediante lenguaje natural.

¿Por qué usar esto?

Si estás creando agentes de IA en Pickaxe, este servidor MCP te permite:

• Analizar conversaciones de agentes - Revisa el historial de chat para identificar brechas de conocimiento y mejorar el rendimiento de los agentes
• Gestionar bases de conocimiento - Crea, actualiza y conecta documentos a tus agentes sin salir de tu flujo de trabajo de IA
• Gestionar usuarios - Crea usuarios, administra accesos, envía invitaciones y realiza seguimiento del uso
• Trabajar con múltiples estudios - Cambia sin problemas entre diferentes estudios de Pickaxe en una sola sesión
• Automatizar flujos de trabajo - Deja que Claude maneje tareas administrativas repetitivas de Pickaxe

Características

Categoría	Herramientas
Estudios	Listar estudios configurados, cambiar entre ellos
Historial de chat	Obtener y analizar registros de conversaciones de agentes
Documentos	Crear, listar, obtener, eliminar, conectar/desconectar de agentes
Usuarios	Crear, listar, obtener, actualizar, eliminar, invitar
Productos	Listar productos y paquetes disponibles
Memoria	Listar esquemas de memoria, recuperar memorias de usuarios

Requisitos previos

• Node.js 18+
• Una cuenta de Pickaxe con acceso a la API
• Tu(s) clave(s) de API de Pickaxe Studio

Instalación

Opción 1: Instalar desde npm (recomendado)

npx mcp-pickaxe

O instalar globalmente:

npm install -g mcp-pickaxe

Opción 2: Clonar y compilar

git clone https://github.com/aplaceforallmystuff/mcp-pickaxe.git
cd mcp-pickaxe
npm install
npm run build

Configuración

1. Obtén tu clave de API de Pickaxe

1. Inicia sesión en Pickaxe Studio
2. Ve a Configuración > API
3. Copia tu clave de API de Studio (comienza con studio-)

2. Configura tu cliente MCP

Para Claude Desktop

Añade a tu archivo de configuración de Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "pickaxe": {
      "command": "node",
      "args": ["/path/to/mcp-pickaxe/dist/index.js"],
      "env": {
        "PICKAXE_STUDIO_MAIN": "studio-your-api-key-here"
      }
    }
  }
}

Para Claude Code

Añade a ~/.claude.json:

{
  "mcpServers": {
    "pickaxe": {
      "command": "node",
      "args": ["/path/to/mcp-pickaxe/dist/index.js"],
      "env": {
        "PICKAXE_STUDIO_MAIN": "studio-your-api-key-here"
      }
    }
  }
}

Configuración multi-estudio

Para trabajar con múltiples estudios de Pickaxe, añade múltiples variables de entorno:

{
  "env": {
    "PICKAXE_STUDIO_PRODUCTION": "studio-xxx-xxx-xxx",
    "PICKAXE_STUDIO_STAGING": "studio-yyy-yyy-yyy",
    "PICKAXE_STUDIO_DEV": "studio-zzz-zzz-zzz",
    "PICKAXE_DEFAULT_STUDIO": "PRODUCTION"
  }
}

Luego especifica qué estudio usar en tus solicitudes:

• Si configuras PICKAXE_DEFAULT_STUDIO, ese estudio se usa cuando no se especifica ninguno
• Si solo hay un estudio configurado, se usa automáticamente
• De lo contrario, pasa studio="STAGING" (o similar) a cualquier herramienta

Casos de uso

Estos son flujos de trabajo reales construidos con mcp-pickaxe en entornos de producción.

1. Monitoreo de seguridad con n8n

Escenario: Detectar intentos de inyección de prompts en más de 29 agentes de IA en tiempo real.

Implementación: Un flujo de trabajo de n8n consulta chat_history cada hora para todos los agentes, ejecuta mensajes contra patrones de detección de inyección (almacenados en Notion) y enruta alertas por severidad:

• ALTO/CRÍTICO → Alerta de Telegram + registro en Notion
• BAJO/MEDIO → Solo registro en Notion

n8n Schedule (hourly)
    → Fetch patterns from Notion
    → Loop through 29 pickaxe IDs
    → Fetch chat_history for each
    → Detect injections (regex patterns)
    → Route by severity → Alert/Log

Herramientas utilizadas: chat_history, studios_list

Resultado: Monitoreo de seguridad en tiempo real en todo un estudio con gestión dinámica de patrones y alertas basadas en severidad.

2. Pipeline de auto-investigación de base de conocimiento

Escenario: Verificar automáticamente y mantener más de 31 artículos de base de conocimiento.

Implementación: Un flujo de trabajo de n8n consulta artículos de KB desde Notion, extrae afirmaciones clave, verifica mediante la API de Perplexity, clasifica los cambios por nivel de riesgo y los enruta a actualización automática o revisión humana.

Daily Schedule (2am)
    → Query KB articles from Notion
    → Filter by day (hash-based, ~1/7th daily)
    → Extract key claims
    → Perplexity fact-check
    → Classify: none/low/major risk
    → Route: auto-update or create review task

Herramientas utilizadas: doc_list, doc_get, doc_create, doc_connect

Resultado: El contenido de KB se mantiene actualizado con verificación automatizada y supervisión humana para cambios importantes.

3. Revisión del rendimiento de agentes

Escenario: Revisión trimestral de un estudio de entrenamiento para identificar brechas de KB y puntos débiles de los usuarios.

Flujo de trabajo:

1. "Fetch chat history from my training agents"
2. "Analyze: which questions got unclear or uncertain responses?"
3. "List all KB documents - which topics are missing?"
4. "Check user stats - who's most active, who's churning?"
5. "Create KB documents addressing the top 3 gaps"
6. "Connect new documents to the relevant agents"

Herramientas utilizadas: chat_history, doc_list, doc_create, doc_connect, user_list

Resultado: Mejoras de KB basadas en datos y conversaciones reales de usuarios, en lugar de suposiciones.

4. Operaciones multi-estudio

Escenario: Gestionar múltiples estudios de Pickaxe desde una sola sesión de Claude.

Configuración:

{
  "env": {
    "PICKAXE_STUDIO_PRODUCTION": "studio-xxx",
    "PICKAXE_STUDIO_STAGING": "studio-yyy",
    "PICKAXE_STUDIO_DEV": "studio-zzz",
    "PICKAXE_DEFAULT_STUDIO": "PRODUCTION"
  }
}

Flujo de trabajo:

1. "List users in PRODUCTION - how many signups this month?"
2. "Switch to STAGING - list products"
3. "Compare KB document counts across all studios"
4. "Find which studio has the most chat activity"

Herramientas utilizadas: studios_list, user_list, doc_list, products_list

Resultado: Visibilidad entre estudios sin cambiar de contexto ni de claves de API manualmente.

5. Auditoría de memoria de usuarios

Escenario: Revisar qué recuerdan tus agentes sobre los usuarios para personalización y cumplimiento de privacidad.

Flujo de trabajo:

1. "List all memory schemas defined in the studio"
2. "Get memories for user@example.com"
3. "What does the system know about this user's situation?"
4. "Which memory fields are most populated across users?"

Ejemplo de salida:

User: maria.example@email.com
Nickname: "Cautious Educator from Madrid"
Summary: "Teaching [language] for [platform] at low hourly rate,
         considering self-employment status due to
         uncertain income"
Memories: 1 stored

Herramientas utilizadas: memory_list, memory_get_user, user_list

Resultado: Visibilidad de los datos de personalización tanto para la mejora del producto como para el cumplimiento del GDPR.

---

Ejemplos de inicio rápido

Una vez configurado, puedes interactuar con Pickaxe mediante lenguaje natural:

Analizar el rendimiento de agentes

"Muéstrame las últimas 20 conversaciones de mi agente de soporte"

"¿Qué preguntas hacen los usuarios que mi agente no puede responder?"

Gestionar base de conocimiento

"Crea un nuevo documento llamado 'FAQ' con este contenido: [tu contenido]"

"Conecta el documento FAQ a mi agente de soporte al cliente"

"Lista todos los documentos de mi base de conocimiento"

Gestión de usuarios

"Muéstrame todos los usuarios y sus estadísticas de uso"

"Crea un nuevo usuario con el correo user@example.com y dale acceso al producto Pro"

"Envía invitaciones a estos correos: [lista de correos]"

Operaciones multi-estudio

"Lista todos los usuarios de mi estudio de staging"

"Compara los documentos entre producción y staging"

Herramientas disponibles

Gestión de estudios

• studios_list - Lista todos los estudios configurados y el predeterminado actual

Historial de chat

• chat_history - Obtiene el historial de conversaciones de un agente
  • Parámetros: pickaxeId, skip, limit, format ("messages" o "raw"), studio

Gestión de documentos

• doc_create - Crea un documento a partir de contenido o URL
• doc_list - Lista todos los documentos (con paginación)
• doc_get - Obtiene un documento específico
• doc_delete - Elimina un documento
• doc_connect - Vincula un documento a un agente
• doc_disconnect - Desvincula un documento de un agente

Gestión de usuarios

• user_list - Lista todos los usuarios con información de acceso y uso
• user_get - Obtiene un usuario específico por correo electrónico
• user_create - Crea un nuevo usuario
• user_update - Actualiza detalles, productos o uso del usuario
• user_delete - Elimina un usuario
• user_invite - Envía invitaciones por correo electrónico

Productos

• products_list - Lista productos/paquetes disponibles

Memoria

• memory_list - Lista esquemas de memoria
• memory_get_user - Obtiene las memorias recopiladas de un usuario

Desarrollo

# Run in development mode (auto-reloads)
npm run dev

# Build for production
npm run build

# Run the built version
npm start

Solución de problemas

"No hay estudios de Pickaxe configurados"

Asegúrate de tener al menos una variable de entorno PICKAXE_STUDIO_* configurada en tu configuración de MCP.

"Estudio no encontrado"

Verifica que el nombre del estudio coincida exactamente (sin distinguir mayúsculas/minúsculas). Ejecuta studios_list para ver las opciones disponibles.

"Error de API de Pickaxe (401)"

Tu clave de API no es válida o ha caducado. Obtén una nueva desde la configuración de Pickaxe Studio.

"Error de API de Pickaxe (403)"

Tu clave de API no tiene permiso para esta operación. Revisa los permisos de tu cuenta de Pickaxe.

Contribuciones

¡Las contribuciones son bienvenidas! Consulta CONTRIBUTING.md para conocer las pautas.

Licencia

Licencia MIT - consulta LICENSE para más detalles.

Enlaces

• Plataforma Pickaxe
• Pickaxe Studio
• Model Context Protocol
• Especificación MCP