Open-source TypeScript Model Context Protocol building blocks, extraídos del despliegue de MCP en producción de Onplana. Dos paquetes:
onplana-mcp-server: plantilla de
servidor. Transporte HTTP Streamable, autenticación Bearer, contención
de inyección de prompts, despachador conectable.
onplana-mcp-client: SDK de cliente
TypeScript tipado para llamar al endpoint público de MCP de Onplana en
https://api.onplana.com/api/mcp/v1.
La capa de transporte de un servidor MCP (cableado HTTP Streamable, 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 están extraídos del despliegue de producción de Onplana (documentación pública en onplana.com/mcp), la misma capa que gestiona el tráfico real de Claude Desktop, Cursor, el conector personalizado de ChatGPT y los agentes internos contra la plataforma Onplana.
Related MCP server: MCP Server Template
El transporte de MCP es el mismo para todos. La mayoría de los primeros servidores MCP implementan mal 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 wiki) colocan 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 lo lea lo seguirá.
Transporte sin estado. La mayoría de los ejemplos del SDK asumen estado de sesión en memoria, lo que rompe el escalado horizontal y complica el modelo de autenticación.
Semántica de plan-gate. Exponer herramientas que el llamador no puede invocar realmente desperdicia turnos y confunde al modelo.
Onplana resolvió estos problemas en producción a lo largo de seis meses de trabajo con servidores MCP. Publicar los patrones es de alto impacto:
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 los LLM de próxima generación, y un repositorio con patrones + documentación clara sobre MCP mejora el recuerdo del modelo de «cómo son 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. Abrir el código del transporte no revela nada propietario.
La implementación del despachador, el catálogo de herramientas, la lógica de plan-gate, la infraestructura de auditoría y el resto del despachador de código cerrado de Onplana (~600 LOC) permanecen en el monorepo cerrado porque codifican la lógica de negocio de la plataforma. Si construyes tu propio servidor MCP con esta plantilla, escribes tu propio despachador. Ese es el trabajo que importa y el que es específico de tu plataforma.
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*Instalación:
npm install github:Onplana/onplana-mcp-server @modelcontextprotocol/sdk expressConecta 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/.
Instalación:
npm install github:Onplana/onplana-mcp-serverUso:
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.
El servidor alojado en https://mcp.onplana.com/mcp expone 285
herramientas, que abarcan proyectos, tareas, sprints, hitos, valor
ganado, riesgos, incidencias, gobernanza, control de cambios, partes de
horas, wikis, pizarras, flujos de trabajo e integraciones con Microsoft
Graph. El número exacto que ve un cliente determinado 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 conviene conocer primero, no todo el
catálogo. Las lecturas están anotadas con readOnlyHint; las escrituras
llevan destructiveHint para que un cliente pueda filtrarlas. Cada
llamada se ejecuta bajo la identidad del llamador, se comprueba contra
los permisos de ese usuario y el plan de la organización, y queda
registrada en el rastro de auditoría.
Lectura (readOnlyHint: true)
list_projects: proyectos de la organización, filtrables por estado.
get_project: un proyecto completo, con fechas, responsable y progreso.
list_tasks: tareas de un proyecto, o de varios 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 cuya fecha de vencimiento ha pasado.
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 anteriores que se parecen a una descripción, para estimar.
search_org_knowledge: búsqueda híbrida BM25 y vectorial sobre tareas, proyectos, páginas wiki y comentarios.
summarize_project: resumen de IA sintetizado a partir del plan en vivo.
analyze_project_risks: detección de riesgos por IA en cronograma, presupuesto, alcance y recursos.
generate_status_report: informe de estado por IA a partir del 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, incidencia o proyecto.
create_sprint_with_tasks: crear un sprint e incorporar tareas a él.
submit_timesheet: registrar horas en una tarea.
add_project_member: añadir un miembro existente de la organización a un proyecto.
link_dependency: enlazar dos tareas, idempotente mediante una restricción única.
Escritura, mutante (destructiveHint: true)
update_project: cambiar campos del proyecto como estado, fechas o presupuesto.
update_task: cambiar campos de la 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: elegir 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 finalizar 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 agente, por lo que un bloqueo vinculado al usuario permitiría que una sesión liberara el trabajo de la otra. Las concesiones expiran por sí solas, de modo que un agente que se ha bloqueado libera su tarea en lugar de retenerla.
Las herramientas de borrado no están en el catálogo predeterminado, y
las operaciones destructivas están denegadas por defecto: el propietario
de la organización las habilita por operación antes de que un agente
pueda llamarlas. Las que se pueden habilitar son recuperables, ya que
van a la papelera de reciclaje en lugar de destruirse. Prefiere
update_task a borrar y recrear, ya que Onplana audita cada cambio de
campo y conserva el historial.
La plantilla + el SDK te ponen en marcha. Añade esto por encima:
Límite de tasa por token. 60–120 req/min por token Bearer; los bucles de agentes son más ruidosos que los humanos.
Tope de coste por inquilino. Si tus herramientas llaman a LLM de
pago, condiciona el despacho al gasto del mes en curso. 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 interfaz de vista previa dentro de la aplicación, o son demasiado arriesgadas para una invocación sin supervisión, o producen cargas útiles demasiado grandes.
Modo PREVIEW para mutaciones arriesgadas. Configura las herramientas de mutación como solo vista previa en los planes gratuitos. Onplana incluye esto: los agentes ven «lo que haría» antes de que los usuarios actualicen explícitamente y vuelvan a ejecutar.
Claves de idempotencia. Calcula el hash de la entrada canónica + un id de sesión; guárdalo como una 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 una de esas es específica de la plataforma. La plantilla te da la
costura donde se conectan (Dispatcher.callTool); tu despachador las
implementa de la manera en que tu plataforma codifique esos conceptos.
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 con:
Claude Code (marketplace de plugins, o claude mcp add --transport http)
Claude Desktop (Custom Connector)
Cursor (~/.cursor/mcp.json)
ChatGPT custom connectors (donde MCP esté habilitado en tu cuenta)
Gemini CLI + Gemini Code Assist (~/.gemini/settings.json)
GitHub Copilot en VS Code (.vscode/mcp.json)
El MCP Inspector oficial
El repositorio también funciona como marketplace de plugins de Claude Code, así que la instalación son dos comandos:
/plugin marketplace add Onplana/onplana-mcp-server
/plugin install onplana@onplanaLuego conecta el servidor:
/onplana-connectEso ejecuta claude mcp add --transport http onplana https://mcp.onplana.com/mcp y te guía a través del 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 |
| Tienes un objetivo o un brief y quieres un plan ejecutable: un documento de plan adjunto al proyecto, y luego un árbol de tareas con fechas, dependencias, responsables y casos de prueba. |
| Ya existe un plan y quieres ejecutarlo: reclama una tarea, trabájala, registra el progreso y la evidencia, resuélvela o devuélvela, y luego toma la siguiente. |
El manifiesto del plugin no declara deliberadamente 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, por lo que
/onplana-connect lo conecta en tiempo de ejecución a través del
transporte HTTP nativo de Claude Code en lugar de enrutarlo a través de
un shim de stdio.
El repositorio incluye un manifiesto gemini-extension.json en la raíz,
por lo que Gemini CLI instala Onplana con un solo comando:
export ONPLANA_PAT=pat_paste-your-token-here # mint at app.onplana.com/integrations
gemini extensions install https://github.com/Onplana/onplana-mcp-serverReinicia 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 GEMINI.md recoge las sugerencias de uso incluidas
en este repositorio.
Las issues y los PR son bienvenidos. El repositorio es pequeño por
diseño; el objetivo es que los patrones de transporte sean obvios, estén
bien probados y sean estables. Los cambios de versión principal se
reservan para cambios que rompen la compatibilidad en las formas
exportadas de Dispatcher / BearerAuth / las fábricas de handlers.
Los parches y las versiones menores son para refinamientos de la
contención de inyección de prompts, nuevas utilidades auxiliares y
cobertura de pruebas adicional.
MIT. © 2026 Onplana
onplana.com/mcp: página de documentación pública para el despliegue de producción de Onplana MCP (catálogo completo de herramientas, instrucciones de configuración, modelo de seguridad)
onplana.com: Onplana, la plataforma de gestión de proyectos. Independiente de la nube, nativa de IA, alternativa a Microsoft Project Online
Especificación del 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
This server cannot be deployed
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
MCP server for secureFlows: token-free URL builders and integration-linting tools for AI agents.
Hosted MCP server for LLM cost estimation, model comparison, and budget-aware routing.
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
