Onplana

Conecta Claude, ChatGPT, Cursor, Gemini y GitHub Copilot a tu portafolio de proyectos de Onplana. 27 herramientas, autenticación OAuth + PAT, registro de auditoría completo.

GitHub

Prueba este MCPPatrocinado

Documentación

Servidor MCP de Onplana

Bloques de construcción de Model Context Protocol en TypeScript de código abierto, extraídos del despliegue MCP de producción de Onplana. Dos paquetes:

onplana-mcp-server: plantilla de servidor. Transporte HTTP transmisible, autenticación Bearer, contención de inyección de prompts, despachador conectable.
onplana-mcp-client: SDK de cliente TypeScript tipado para llamar al endpoint MCP público de Onplana en https://api.onplana.com/api/mcp/v1.

Qué es esto

La capa de transporte de un servidor MCP (conexión HTTP transmisible, modo sin estado, autenticación Bearer con alcance, contención de inyección de prompts) bien hecha, separada del registro de herramientas específico de la plataforma. Usa la plantilla de servidor para construir tu propio servidor MCP con las mejores prácticas de seguridad integradas. Usa el SDK de cliente para manejar el MCP alojado de Onplana desde tu propio código.

Los patrones se extraen del despliegue de producción de Onplana (documentación pública en onplana.com/mcp), la misma capa que maneja el tráfico real de Claude Desktop, Cursor, el conector personalizado de ChatGPT y agentes internos contra la plataforma Onplana.

Por qué código abierto

El transporte MCP es el mismo para todos. La mayoría de los primeros servidores MCP fallan en los primitivos de seguridad:

Inyección de prompts. Las herramientas que devuelven contenido generado por el usuario (títulos de tareas, cuerpos de comentarios, texto de wikis) ponen ese contenido directamente en el contexto del modelo. Sin contención, un actor hostil puede plantar "ignore previous instructions" en sus propios datos y el siguiente agente que los lea seguirá sus instrucciones.
Transporte sin estado. La mayoría de los ejemplos de SDK asumen estado de sesión en memoria, lo que rompe el escalado horizontal y complica el modelo de autenticación.
Semántica de puerta de plan. Mostrar herramientas que el llamador no puede invocar realmente desperdicia turnos y confunde al modelo.

Onplana resolvió estos problemas en producción durante seis meses de trabajo en servidores MCP. Publicar los patrones es de alto apalancamiento:

Otros autores de MCP obtienen una plantilla probada en lugar de reinventar la rueda.
El repositorio es una superficie de señal de preentrenamiento. Los README públicos de GitHub tienen mucho peso en los datos de entrenamiento de las LLM de próxima generación, y un repositorio con patrones + documentación clara sobre MCP mejora el recuerdo del modelo de "cómo se ven los buenos servidores MCP".
La interfaz del despachador es la costura donde se conecta tu lógica de negocio. El transporte es genérico; lo que importa de tu servidor MCP es el registro de herramientas. Publicar el transporte como código abierto no regala nada propietario.

La implementación del despachador, el catálogo de herramientas, la lógica de puerta de plan, la infraestructura de auditoría y el resto del despachador cerrado de Onplana (~600 líneas de código) permanecen en el monorepositorio cerrado porque codifican la lógica de negocio de la plataforma. Si construyes tu propio servidor MCP usando esta plantilla, escribes tu propio despachador. Ese es el trabajo que importa y el que es específico de tu plataforma.

Estructura del repositorio

onplana-mcp-server/
├── packages/
│   ├── server-template/        # onplana-mcp-server (npm)
│   │   ├── src/
│   │   │   ├── transport.ts    # Streamable HTTP wiring
│   │   │   ├── auth.ts         # Bearer auth pattern
│   │   │   ├── promptInjection.ts  # wrapUserContent + escape
│   │   │   ├── dispatcher.ts   # Pluggable Dispatcher interface
│   │   │   └── index.ts
│   │   ├── tests/              # promptInjection + auth + transport
│   │   └── README.md
│   └── client/                 # onplana-mcp-client (npm)
│       ├── src/
│       │   ├── client.ts       # OnplanaMcpClient class
│       │   ├── types.ts        # Public type surface
│       │   └── index.ts
│       ├── tests/              # client.test.ts (stub fetch)
│       └── README.md
├── .claude-plugin/
│   └── marketplace.json        # Claude Code marketplace
├── plugins/
│   └── onplana/                # Claude Code plugin (skills + connect command)
├── examples/
│   └── in-memory/              # Runnable demo with 3 toy tools
├── gemini-extension.json       # Gemini CLI manifest
├── mcp.json                    # stdio client config (mcp-remote)
├── server.json                 # MCP registry manifest
└── .github/workflows/
    ├── ci.yml                  # tsc + vitest on PR
    └── publish.yml             # npm publish on tag v*

Inicio rápido

Construir un servidor

Instala:

npm install github:Onplana/onplana-mcp-server @modelcontextprotocol/sdk express

Conecta una aplicación Express:

import express from 'express'
import {
  createMcpPostHandler,
  createMcpMethodNotAllowedHandler,
  requireBearerAuth,
  type Dispatcher,
} from 'onplana-mcp-server'

const dispatcher: Dispatcher = {
  async listTools(ctx) { /* return your tool descriptors */ return [] },
  async callTool(name, input, ctx) { /* dispatch to your tools */ return { output: {} } },
}

const auth = async (token: string) => {
  // Validate against your token store. Return AuthContext or null.
  return { userId: 'u', scopes: ['MCP_AGENT'] }
}

const app = express()
app.use(express.json())
app.use('/api/mcp/v1',
  requireBearerAuth({ auth, requiredScope: 'MCP_AGENT' }),
)
app.post('/api/mcp/v1', createMcpPostHandler({ dispatcher }))
app.get('/api/mcp/v1', createMcpMethodNotAllowedHandler())
app.delete('/api/mcp/v1', createMcpMethodNotAllowedHandler())
app.listen(3000)

Inicio rápido completo en packages/server-template/README.md; demo ejecutable en examples/in-memory/.

Manejar Onplana desde código

Instala:

npm install github:Onplana/onplana-mcp-server

Usa:

import { OnplanaMcpClient } from 'onplana-mcp-client'

const client = new OnplanaMcpClient({
  url:   'https://api.onplana.com/api/mcp/v1',
  token: process.env.ONPLANA_PAT!,
})

const projects = await client.listProjects({ status: 'ACTIVE' })

// The differentiator vs other PM-tool MCPs: hybrid semantic + lexical
// search across your org's indexed content (projects, tasks, risks,
// goals, comments, wiki pages).
const { matches } = await client.searchOrgKnowledge({
  query: 'rationale for the 3-week design phase',
  scope: 'all',
  limit: 5,
})

Documentación completa del cliente en packages/client/README.md.

Herramientas

El servidor alojado en https://mcp.onplana.com/mcp expone 285 herramientas, que abarcan proyectos, tareas, sprints, hitos, valor ganado, riesgos, problemas, gobernanza, control de cambios, hojas de tiempo, wikis, pizarras, flujos de trabajo e integraciones con Microsoft Graph. El número exacto que ve un cliente dado es menor, porque las herramientas se filtran por el rol del llamador y el plan de la organización antes de servir el catálogo.

Las 33 siguientes son las que vale la pena conocer primero, no todo el catálogo. Las lecturas se anotan con readOnlyHint; las escrituras llevan destructiveHint para que un cliente pueda filtrarlas. Cada llamada se ejecuta bajo la identidad del llamador, se verifica contra los permisos de ese usuario y el plan de la organización, y queda en el registro de auditoría.

Lectura (readOnlyHint: true)

list_projects: proyectos en la organización, filtrables por estado.
get_project: un proyecto completo, con fechas, propietario y progreso.
list_tasks: tareas de un proyecto, o entre proyectos.
get_task: una tarea con descripción, asignado, fechas y comentarios recientes.
list_my_tasks: tareas asignadas al usuario que llama.
list_overdue: tareas vencidas.
list_team_members: miembros de un proyecto.
list_org_members: miembros de la organización.
list_risks: riesgos registrados contra un proyecto.
find_similar_projects: proyectos pasados que se parecen a una descripción, para estimar.
search_org_knowledge: búsqueda híbrida BM25 y vectorial sobre tareas, proyectos, páginas de wiki y comentarios.
summarize_project: resumen de IA sintetizado desde el plan en vivo.
analyze_project_risks: detección de riesgos con IA en cronograma, presupuesto, alcance y recursos.
generate_status_report: informe de estado con IA desde el cronograma y la actividad actuales.
search: adaptador de App Directory, devuelve {id, title, snippet?, url?}.
fetch: adaptador de App Directory, devuelve {id, title, content, url?, metadata?}.

Escritura, aditiva (destructiveHint: false)

create_project: crear un proyecto.
create_task: crear una tarea, opcionalmente bajo una tarea padre.
create_milestone: añadir un hito a un proyecto.
create_comment: comentar en una tarea, problema o proyecto.
create_sprint_with_tasks: crear un sprint y mover tareas a él.
submit_timesheet: registrar horas contra una tarea.
add_project_member: añadir un miembro existente de la organización a un proyecto.
link_dependency: vincular dos tareas, idempotente mediante una restricción única.

Escritura, mutante (destructiveHint: true)

update_project: cambiar campos de proyecto como estado, fechas o presupuesto.
update_task: cambiar campos de tarea como estado, progreso o fechas.
bulk_update_tasks: aplicar un cambio a muchas tareas.
assign_task: establecer el asignado de una tarea.
move_task_to_sprint: mover una tarea dentro o fuera de un sprint.

Concesiones (para agentes que comparten un backlog)

next_task: tomar la siguiente tarea disponible y reclamarla en una sola llamada. Listar y luego reclamar deja un hueco en el que dos agentes pueden caer.
claim_task: tomar una concesión exclusiva sobre una tarea específica.
renew_task_lease: extender una concesión mientras el trabajo sigue en curso.
release_task: devolver la concesión; completar o bloquear una tarea también la libera, y terminar una sesión libera todo lo que esa ejecución mantiene.

Una concesión está vinculada a la EJECUCIÓN, no al usuario. Dos sesiones de un mismo cliente se autentican como la misma persona de agente, por lo que un bloqueo por usuario permitiría que una sesión libere el trabajo de la otra. Las concesiones expiran solas, así que un agente que se bloquea libera su tarea en lugar de retenerla.

Las herramientas de borrado no están en el catálogo predeterminado, y las operaciones destructivas se deniegan por defecto: el propietario de una organización las habilita por operación antes de que un agente pueda llamarlas. Las que se pueden habilitar son recuperables, y van a la papelera de reciclaje en lugar de destruirse. Prefiere update_task sobre borrar y recrear de todos modos, ya que Onplana audita cada cambio de campo y conserva el historial.

Lista de verificación de producción

La plantilla + el SDK te ponen en marcha. Añade esto encima:

Límite de velocidad por token. 60–120 solicitudes/min por token Bearer; los bucles de agentes son más ruidosos que los humanos.
Tope de costo por inquilino. Si tus herramientas llaman a LLM de pago, filtra el despacho según el gasto del mes hasta la fecha. El despliegue de Onplana usa aiMonthlyCostCapUsd con modos WARN / BLOCK.
Registro de auditoría. Cada despacho debería escribir una fila de auditoría etiquetada con actorType: 'mcp_agent' para que los administradores puedan ver lo que los agentes de IA hicieron en su inquilino por separado de la actividad humana.
Curación de plan / alcance. No expongas todas las herramientas internas. Onplana expone 21 de 26; las 5 suprimidas o necesitan una UI de vista previa en la aplicación, son demasiado arriesgadas para invocación sin supervisión, o producen cargas útiles demasiado grandes.
Modo PREVIEW para mutaciones arriesgadas. Configura las herramientas mutantes como solo vista previa en los niveles gratuitos. Onplana incluye esto: los agentes ven "qué haría" antes de que los usuarios actualicen explícitamente y vuelvan a ejecutar.
Claves de idempotencia. Hashea la entrada canónica + un id de sesión; guárdalo como restricción única en tu fila de auditoría. Un modelo que reintenta la misma acción lógica no debería crear dos veces.

Cada uno de estos es específico de la plataforma. La plantilla te da la costura donde se conectan (Dispatcher.callTool); tu despachador los implementa como tu plataforma codifique esos conceptos.

Compatibilidad

Node.js ≥ 20 (para la plantilla de servidor y la matriz de CI); ≥ 18 para el cliente (usa fetch ambiental).
@modelcontextprotocol/sdk@^1.29.0
express@^4.18.0 o express@^5.0.0

Probado contra:

Claude Code (mercado de plugins, o claude mcp add --transport http)
Claude Desktop (Conector personalizado)
Cursor (~/.cursor/mcp.json)
Conectores personalizados de ChatGPT (donde MCP esté habilitado en tu cuenta)
Gemini CLI + Gemini Code Assist (~/.gemini/settings.json)
GitHub Copilot en VS Code (.vscode/mcp.json)
El Inspector MCP oficial

Instalar en Claude Code

El repositorio funciona también como mercado de plugins de Claude Code, así que instalar son dos comandos:

/plugin marketplace add Onplana/onplana-mcp-server
/plugin install onplana@onplana

Luego adjunta el servidor:

/onplana-connect

Eso ejecuta claude mcp add --transport http onplana https://mcp.onplana.com/mcp y te guía por el inicio de sesión en el navegador. El servidor MCP está disponible en todos los planes de Onplana, incluido el gratuito.

El plugin incluye las dos habilidades de agente de Onplana, invocadas como onplana:<name>:

Habilidad	Úsala cuando
`onplana-project-planner`	Tienes un objetivo o un resumen y quieres un plan ejecutable: un documento de plan adjunto al proyecto, luego un árbol de tareas con fechas, dependencias, propietarios y casos de prueba.
`onplana-autonomous-agent`	Ya existe un plan y quieres ejecutarlo: reclama una tarea, trabájala, registra progreso y evidencia, resuélvela o devuélvela, y luego toma la siguiente.

El manifiesto del plugin deliberadamente no declara ningún servidor MCP. Un plugin declara servidores en la forma stdio (command, args, env), y el de Onplana es remoto y autenticado con OAuth, así que /onplana-connect lo adjunta en tiempo de ejecución a través del transporte HTTP nativo de Claude Code en lugar de enrutarlo por un shim de stdio.

Instalar en Gemini CLI

El repositorio incluye un manifiesto gemini-extension.json en la raíz, así que Gemini CLI instala Onplana con un comando:

export ONPLANA_PAT=pat_paste-your-token-here  # mint at app.onplana.com/integrations
gemini extensions install https://github.com/Onplana/onplana-mcp-server

Reinicia la CLI de gemini (o recarga tu ventana de VS Code / JetBrains si usas Gemini Code Assist). Las herramientas de Onplana aparecen en /mcp y tu contexto de GEMINI.md recoge las sugerencias de uso incluidas en este repositorio.

Contribuciones

Las issues y los PRs son bienvenidos. El repositorio es pequeño por diseño; el objetivo es que los patrones de transporte sean obvios, bien probados y estables. Los cambios de versión mayor se reservan para cambios que rompen compatibilidad en las formas exportadas de Dispatcher / BearerAuth / fábrica de manejadores. Los parches y menores son para refinamientos de contención de inyección de prompts, nuevas utilidades auxiliares y cobertura de pruebas adicional.

Licencia

Ver también

onplana.com/mcp: página de documentación pública del despliegue MCP de producción de Onplana (catálogo completo de herramientas, instrucciones de configuración, modelo de seguridad)
onplana.com: Onplana, la plataforma de gestión de proyectos. Alternativa a Microsoft Project Online, agnóstica de nube y nativa de IA
Especificación de Model Context Protocol: el estándar MCP
Guía de inyección de prompts de Anthropic: el patrón de seguridad que implementa el envoltorio de este repositorio