Onplana MCP server

Open-Source-TypeScript-Bausteine für das Model Context Protocol, extrahiert aus der MCP-Produktionsumgebung von Onplana. Zwei Pakete:

• onplana-mcp-server: Servervorlage. Streamable-HTTP-Transport, Bearer-Authentifizierung, Eindämmung von Prompt-Injection, austauschbarer Dispatcher.

• onplana-mcp-client: typisiertes TypeScript-Client-SDK zum Aufrufen des öffentlichen Onplana-MCP-Endpunkts unter https://api.onplana.com/api/mcp/v1.

Was das ist

Die Transportschicht eines MCP-Servers (Streamable-HTTP-Verdrahtung, zustandsloser Modus, eingeschränkte Bearer-Authentifizierung, Eindämmung von Prompt-Injection) – gut umgesetzt und getrennt von der plattformspezifischen Tool-Registry. Verwenden Sie die Servervorlage, um Ihren eigenen MCP-Server mit integrierten Sicherheits-Best-Practices zu erstellen. Verwenden Sie das Client-SDK, um das gehostete MCP von Onplana aus Ihrem eigenen Code anzusteuern.

Die Muster stammen aus Onplanas Produktionsumgebung (öffentliche Dokumentation unter onplana.com/mcp) – derselben Schicht, die den realen Datenverkehr von Claude Desktop, Cursor, ChatGPT Custom Connector und internen Agenten gegen die Onplana-Plattform abwickelt.

Related MCP server: MCP Server Template

Warum Open Source

Der MCP-Transport ist für alle gleich. Die meisten frühen MCP-Server setzen die Sicherheitsgrundlagen falsch um:

• Prompt-Injection. Tools, die nutzergenerierte Inhalte zurückgeben (Aufgabentitel, Kommentartexte, Wiki-Text), platzieren diese Inhalte direkt im Kontext des Modells. Ohne Eindämmung kann ein Angreifer "ignore previous instructions" in seinen eigenen Daten verstecken, und der nächste Agent, der sie liest, folgt ihnen.

• Zustandsloser Transport. Die meisten SDK-Beispiele gehen von In-Memory-Sitzungszustand aus, was die horizontale Skalierung bricht und das Authentifizierungsmodell verkompliziert.

• Plan-Gate-Semantik. Tools anzuzeigen, die der Aufrufer nicht wirklich ausführen kann, verschwendet Turns und verwirrt das Modell.

Onplana hat diese Probleme in sechs Monaten MCP-Server-Entwicklung in der Produktion gelöst. Die Muster zu veröffentlichen bringt einen großen Hebel:

1. Andere MCP-Autoren erhalten eine bewährte Vorlage, statt das Rad neu zu erfinden.

2. Das Repository ist eine Oberfläche für Pretraining-Signale. Öffentliche GitHub-READMEs werden in den Trainingsdaten der nächsten LLM-Generation stark gewichtet, und ein Repository mit Mustern + klarer Dokumentation über MCP verbessert das Modell-Abrufverhalten (Recall) darüber, „wie gute MCP-Server aussehen“.

3. Die Dispatcher-Schnittstelle ist die Nahtstelle, an der Ihre Geschäftslogik andockt. Der Transport ist generisch; was bei Ihrem MCP-Server zählt, ist die Tool-Registry. Den Transport als Open Source zu veröffentlichen, gibt nichts Proprietäres preis.

Die Dispatcher-Implementierung, der Tool-Katalog, die Plan-Gate-Logik, die Audit-Infrastruktur und der Rest von Onplanas ~600 LOC umfassenden Closed-Source-Dispatcher bleiben im geschlossenen Monorepo, weil sie die Geschäftslogik der Plattform abbilden. Wenn Sie mit dieser Vorlage Ihren eigenen MCP-Server bauen, schreiben Sie Ihren eigenen Dispatcher. Das ist die Arbeit, die zählt, und die Arbeit, die für Ihre Plattform spezifisch ist.

Repository-Struktur

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*

Schnellstart

Einen Server erstellen

Installieren:

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

Eine Express-App anbinden:

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)

Der vollständige Schnellstart steht in packages/server-template/README.md; eine ausführbare Demo in examples/in-memory/.

Onplana aus dem eigenen Code ansteuern

Installieren:

npm install github:Onplana/onplana-mcp-server

Verwendung:

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,
})

Die vollständige Client-Dokumentation finden Sie in packages/client/README.md.

Tools

Der gehostete Server unter https://mcp.onplana.com/mcp stellt 285 Tools bereit, die Projekte, Aufgaben, Sprints, Meilensteine, Earned Value, Risiken, Issues, Governance, Änderungskontrolle, Zeiterfassung, Wikis, Whiteboards, Workflows und die Microsoft-Graph-Integrationen abdecken. Die genaue Anzahl, die ein bestimmter Client sieht, ist kleiner, weil die Tools vor der Auslieferung des Katalogs nach der Rolle des Aufrufers und dem Plan der Organisation gefiltert werden.

Die folgenden 33 sind diejenigen, die man zuerst kennen sollte, nicht der gesamte Katalog. Lesezugriffe sind mit readOnlyHint gekennzeichnet; Schreibzugriffe tragen destructiveHint, damit ein Client sie abschirmen kann. Jeder Aufruf läuft unter der Identität des Aufrufers, wird gegen die Berechtigungen dieses Benutzers und den Plan der Organisation geprüft und landet im Audit-Trail.

Lesen (readOnlyHint: true)

• list_projects: Projekte in der Organisation, filterbar nach Status.

• get_project: Ein vollständiges Projekt mit Terminen, Verantwortlichem und Fortschritt.

• list_tasks: Aufgaben für ein Projekt oder projektübergreifend.

• get_task: Eine einzelne Aufgabe mit Beschreibung, Bearbeiter, Terminen und letzten Kommentaren.

• list_my_tasks: Aufgaben, die dem aufrufenden Benutzer zugewiesen sind.

• list_overdue: Aufgaben, deren Fälligkeitsdatum überschritten ist.

• list_team_members: Mitglieder eines Projekts.

• list_org_members: Mitglieder der Organisation.

• list_risks: Risiken, die für ein Projekt erfasst wurden.

• find_similar_projects: Frühere Projekte, die einer Beschreibung ähneln, zur Schätzung.

• search_org_knowledge: Hybride BM25- und Vektorsuche über Aufgaben, Projekte, Wiki-Seiten und Kommentare.

• summarize_project: KI-Zusammenfassung, die aus dem aktuellen Plan erstellt wird.

• analyze_project_risks: KI-gestützte Risikoerkennung über Zeitplan, Budget, Umfang und Ressourcen.

• generate_status_report: KI-Statusbericht aus dem aktuellen Zeitplan und der aktuellen Aktivität.

• search: App-Directory-Adapter, gibt {id, title, snippet?, url?} zurück.

• fetch: App-Directory-Adapter, gibt {id, title, content, url?, metadata?} zurück.

Schreiben, additiv (destructiveHint: false)

• create_project: Ein Projekt erstellen.

• create_task: Eine Aufgabe erstellen, optional unter einer übergeordneten Aufgabe.

• create_milestone: Einen Meilenstein zu einem Projekt hinzufügen.

• create_comment: Eine Aufgabe, ein Issue oder ein Projekt kommentieren.

• create_sprint_with_tasks: Einen Sprint erstellen und Aufgaben hineinziehen.

• submit_timesheet: Stunden für eine Aufgabe erfassen.

• add_project_member: Ein vorhandenes Organisationsmitglied zu einem Projekt hinzufügen.

• link_dependency: Zwei Aufgaben verknüpfen, idempotent über eine Unique-Constraint.

Schreiben, verändernd (destructiveHint: true)

• update_project: Projektfelder wie Status, Termine oder Budget ändern.

• update_task: Aufgabenfelder wie Status, Fortschritt oder Termine ändern.

• bulk_update_tasks: Eine Änderung auf viele Aufgaben anwenden.

• assign_task: Den Bearbeiter einer Aufgabe festlegen.

• move_task_to_sprint: Eine Aufgabe in einen Sprint verschieben oder aus einem Sprint entfernen.

Reservierungen (für Agenten, die sich ein Backlog teilen)

• next_task: Die nächste verfügbare Aufgabe auswählen und in einem Aufruf reservieren. Wenn man erst auflistet und dann reserviert, entsteht eine Lücke, in die zwei Agenten gleichzeitig geraten können.

• claim_task: Eine exklusive Reservierung für eine bestimmte Aufgabe übernehmen.

• renew_task_lease: Eine Reservierung verlängern, während die Arbeit noch läuft.

• release_task: Die Reservierung zurückgeben; auch das Abschließen oder Blockieren einer Aufgabe gibt sie frei, und das Beenden einer Sitzung gibt alles frei, was dieser Lauf hält.

Eine Reservierung ist an den RUN gebunden, nicht an den Benutzer. Zwei Sitzungen eines Clients authentifizieren sich als dieselbe Agent-Persona, sodass eine benutzergebundene Sperre es einer Sitzung ermöglichen würde, die Arbeit der anderen freizugeben. Reservierungen laufen von selbst ab, sodass ein abgestürzter Agent seine Aufgabe freigibt, statt sie zu blockieren.

Lösch-Tools sind nicht im Standardkatalog enthalten, und destruktive Operationen sind standardmäßig verweigert (Deny-by-Default): Ein Organisationsinhaber muss sie pro Operation aktivieren, bevor ein Agent sie aufrufen kann. Diejenigen, die aktiviert werden können, sind wiederherstellbar und werden in den Papierkorb verschoben, statt zerstört zu werden. Bevorzugen Sie ohnehin update_task gegenüber Löschen-und-Neu-Erstellen, da Onplana jede Feldänderung protokolliert und den Verlauf aufbewahrt.

Produktions-Checkliste

Die Vorlage + das SDK bringen Sie zum Laufen. Ergänzen Sie zusätzlich Folgendes:

• Ratenbegrenzung pro Token. 60–120 Anfragen/min pro Bearer-Token; agentische Schleifen sind lauter als Menschen.

• Kostenobergrenze pro Mandant. Wenn Ihre Tools kostenpflichtige LLMs aufrufen, machen Sie die Dispatch-Freigabe vom bisherigen Monatsverbrauch abhängig. Onplana verwendet dafür aiMonthlyCostCapUsd mit den Modi WARN / BLOCK.

• Audit-Protokollierung. Jeder Dispatch sollte eine Audit-Zeile mit dem Tag actorType: 'mcp_agent' schreiben, damit Administratoren sehen können, was KI-Agenten in ihrem Mandanten getan haben, getrennt von menschlichen Aktivitäten.

• Plan-/Scope-Kuration. Legen Sie nicht jedes interne Tool offen. Onplana legt 21 von 26 offen; die 5 unterdrückten benötigen entweder eine In-App-Vorschau-UI, sind für unbeaufsichtigte Aufrufe zu riskant oder erzeugen übermäßig große Payloads.

• PREVIEW-Modus für riskante Änderungen. Setzen Sie verändernde Tools in kostenlosen Tarifen standardmäßig auf Nur-Vorschau. Onplana liefert das mit: Agenten sehen „was es tun würde“, bevor Benutzer explizit upgraden und erneut ausführen.

• Idempotenz-Schlüssel. Bilden Sie einen Hash aus dem kanonisierten Eingabeobjekt + einer Sitzungs-ID; speichern Sie ihn als Unique-Constraint in Ihrer Audit-Zeile. Ein Modell, das dieselbe logische Aktion erneut versucht, sollte nicht doppelt erstellen.

Jeder dieser Punkte ist plattformspezifisch. Die Vorlage gibt Ihnen die Nahtstelle, an der sie andocken (Dispatcher.callTool); Ihr Dispatcher implementiert sie so, wie Ihre Plattform diese Konzepte abbildet.

Kompatibilität

• Node.js ≥ 20 (für die Servervorlage und die CI-Matrix); ≥ 18 für den Client (nutzt das eingebaute fetch).

• @modelcontextprotocol/sdk@^1.29.0

• express@^4.18.0 oder express@^5.0.0

Getestet mit:

• Claude Code (Plugin-Marketplace oder claude mcp add --transport http)

• Claude Desktop (Custom Connector)

• Cursor (~/.cursor/mcp.json)

• ChatGPT Custom Connectors (sofern MCP in Ihrem Konto aktiviert ist)

• Gemini CLI + Gemini Code Assist (~/.gemini/settings.json)

• GitHub Copilot in VS Code (.vscode/mcp.json)

• Der offizielle MCP Inspector

Installation in Claude Code

Das Repository dient zugleich als Plugin-Marketplace für Claude Code, sodass die Installation aus zwei Befehlen besteht:

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

Dann den Server anbinden:

/onplana-connect

Das führt claude mcp add --transport http onplana https://mcp.onplana.com/mcp aus und führt Sie durch die Browser-Anmeldung. Der MCP-Server ist in jedem Onplana-Tarif verfügbar, auch im kostenlosen.

Das Plugin enthält die beiden Onplana-Agenten-Skills, die als onplana:<name> aufgerufen werden:

Das Plugin-Manifest deklariert bewusst keinen MCP-Server. Ein Plugin deklariert Server in der Stdio-Form (command, args, env), und Onplanas Server ist remote und OAuth-authentifiziert. Deshalb bindet /onplana-connect ihn zur Laufzeit über den nativen HTTP-Transport von Claude Code an, statt ihn durch einen Stdio-Shim zu leiten.

Installation in Gemini CLI

Das Repository enthält im Stammverzeichnis ein Manifest gemini-extension.json, sodass Gemini CLI Onplana mit einem einzigen Befehl installiert:

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

Starten Sie die gemini-CLI neu (oder laden Sie Ihr VS-Code-/JetBrains-Fenster neu, wenn Sie Gemini Code Assist verwenden). Die Onplana-Tools erscheinen in /mcp, und Ihr GEMINI.md-Kontext übernimmt die in diesem Repository enthaltenen Nutzungshinweise.

Mitwirken

Issues und PRs sind willkommen. Das Repository ist bewusst klein gehalten; das Ziel ist, dass die Transportmuster offensichtlich, gut getestet und stabil sind. Major-Version-Sprünge sind Breaking Changes an den exportierten Signaturen von Dispatcher / BearerAuth / Handler-Factory vorbehalten. Patches und Minor-Versionen sind für Verbesserungen bei der Eindämmung von Prompt-Injection, neue Hilfsprogramme und zusätzliche Testabdeckung gedacht.

Lizenz

MIT. © 2026 Onplana

Siehe auch

• onplana.com/mcp: öffentliche Dokumentationsseite für die Produktionsbereitstellung von Onplana MCP (vollständiger Tool-Katalog, Einrichtungsanweisungen, Sicherheitsmodell)

• onplana.com: Onplana, die PM-Plattform. Cloud-agnostisch, KI-nativ, Alternative zu Microsoft Project Online

• Model Context Protocol-Spezifikation: der MCP-Standard

• Anthropic-Leitfaden zur Prompt-Injection: das Sicherheitsmuster, das der Wrapper dieses Repos implementiert