{
  "markdown": "# Onplana MCP server\n\nOpen-source TypeScript Model Context Protocol building blocks,\nextracted from [Onplana](https://onplana.com)'s production MCP\ndeployment. Two packages:\n\n- **[`onplana-mcp-server`](./packages/server-template)**: server\n  template. Streamable HTTP transport, Bearer auth, prompt-injection\n  containment, pluggable dispatcher.\n- **[`onplana-mcp-client`](./packages/client)**: typed TypeScript\n  client SDK for calling the public Onplana MCP endpoint at\n  `https://api.onplana.com/api/mcp/v1`.\n\n[![CI](https://github.com/Onplana/onplana-mcp-server/workflows/CI/badge.svg)](https://github.com/Onplana/onplana-mcp-server/actions)\n[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)\n\n## What this is\n\nThe transport layer of an MCP server (Streamable HTTP wiring,\nstateless mode, scoped Bearer auth, prompt-injection containment)\ndone well, separated from the platform-specific tool registry. Use\nthe **server template** to build your own MCP server with security\nbest practices baked in. Use the **client SDK** to drive Onplana's\nhosted MCP from your own code.\n\nThe patterns are extracted from Onplana's production deployment\n(public docs at [onplana.com/mcp](https://onplana.com/mcp)), the\nsame layer that handles real Claude Desktop, Cursor, ChatGPT custom\nconnector, and in-house agent traffic against the Onplana platform.\n\n## Why open-source\n\nThe MCP transport is the same for everyone. Most early MCP servers\nget the security primitives wrong:\n\n- **Prompt injection.** Tools that return user-generated content\n  (task titles, comment bodies, wiki text) put that content directly\n  into the model's context. Without containment, a hostile actor can\n  plant `\"ignore previous instructions\"` in their own data and the\n  next agent that reads it follows along.\n- **Stateless transport.** Most SDK examples assume in-memory session\n  state, which breaks horizontal scaling and complicates the auth\n  model.\n- **Plan-gate semantics.** Surfacing tools the caller can't actually\n  invoke wastes turns and confuses the model.\n\nOnplana solved these in production over six months of MCP-server\nwork. Publishing the patterns is high-leverage:\n\n1. Other MCP authors get a known-good template instead of\n   reinventing.\n2. The repo is a pretraining-signal surface. Public GitHub READMEs\n   are heavily weighted in next-gen LLM training data, and a repo\n   with patterns + clear documentation about MCP improves model\n   recall of \"what good MCP servers look like.\"\n3. The dispatcher interface is the seam where your business logic\n   plugs in. The transport is generic; what matters about your MCP\n   server is the tool registry. Open-sourcing the transport doesn't\n   give away anything proprietary.\n\nThe dispatcher implementation, tool catalog, plan-gate logic, audit\ninfrastructure, and the rest of Onplana's ~600 LOC closed-source\ndispatcher stay in the closed monorepo because they encode platform\nbusiness logic. If you build your own MCP server using this\ntemplate, you write your own dispatcher. That's the work that\nmatters and the work that's specific to your platform.\n\n## Repository layout\n\n```\nonplana-mcp-server/\n├── packages/\n│   ├── server-template/        # onplana-mcp-server (npm)\n│   │   ├── src/\n│   │   │   ├── transport.ts    # Streamable HTTP wiring\n│   │   │   ├── auth.ts         # Bearer auth pattern\n│   │   │   ├── promptInjection.ts  # wrapUserContent + escape\n│   │   │   ├── dispatcher.ts   # Pluggable Dispatcher interface\n│   │   │   └── index.ts\n│   │   ├── tests/              # promptInjection + auth + transport\n│   │   └── README.md\n│   └── client/                 # onplana-mcp-client (npm)\n│       ├── src/\n│       │   ├── client.ts       # OnplanaMcpClient class\n│       │   ├── types.ts        # Public type surface\n│       │   └── index.ts\n│       ├── tests/              # client.test.ts (stub fetch)\n│       └── README.md\n├── .claude-plugin/\n│   └── marketplace.json        # Claude Code marketplace\n├── plugins/\n│   └── onplana/                # Claude Code plugin (skills + connect command)\n├── examples/\n│   └── in-memory/              # Runnable demo with 3 toy tools\n├── gemini-extension.json       # Gemini CLI manifest\n├── mcp.json                    # stdio client config (mcp-remote)\n├── server.json                 # MCP registry manifest\n└── .github/workflows/\n    ├── ci.yml                  # tsc + vitest on PR\n    └── publish.yml             # npm publish on tag v*\n```\n\n## Quickstart\n\n### Build a server\n\nInstall:\n\n```bash\nnpm install github:Onplana/onplana-mcp-server @modelcontextprotocol/sdk express\n```\n\nWire an Express app:\n\n```ts\nimport express from 'express'\nimport {\n  createMcpPostHandler,\n  createMcpMethodNotAllowedHandler,\n  requireBearerAuth,\n  type Dispatcher,\n} from 'onplana-mcp-server'\n\nconst dispatcher: Dispatcher = {\n  async listTools(ctx) { /* return your tool descriptors */ return [] },\n  async callTool(name, input, ctx) { /* dispatch to your tools */ return { output: {} } },\n}\n\nconst auth = async (token: string) => {\n  // Validate against your token store. Return AuthContext or null.\n  return { userId: 'u', scopes: ['MCP_AGENT'] }\n}\n\nconst app = express()\napp.use(express.json())\napp.use('/api/mcp/v1',\n  requireBearerAuth({ auth, requiredScope: 'MCP_AGENT' }),\n)\napp.post('/api/mcp/v1', createMcpPostHandler({ dispatcher }))\napp.get('/api/mcp/v1', createMcpMethodNotAllowedHandler())\napp.delete('/api/mcp/v1', createMcpMethodNotAllowedHandler())\napp.listen(3000)\n```\n\nFull quickstart in [`packages/server-template/README.md`](./packages/server-template/README.md);\nrunnable demo in [`examples/in-memory/`](./examples/in-memory).\n\n### Drive Onplana from code\n\nInstall:\n\n```bash\nnpm install github:Onplana/onplana-mcp-server\n```\n\nUse:\n\n```ts\nimport { OnplanaMcpClient } from 'onplana-mcp-client'\n\nconst client = new OnplanaMcpClient({\n  url:   'https://api.onplana.com/api/mcp/v1',\n  token: process.env.ONPLANA_PAT!,\n})\n\nconst projects = await client.listProjects({ status: 'ACTIVE' })\n\n// The differentiator vs other PM-tool MCPs: hybrid semantic + lexical\n// search across your org's indexed content (projects, tasks, risks,\n// goals, comments, wiki pages).\nconst { matches } = await client.searchOrgKnowledge({\n  query: 'rationale for the 3-week design phase',\n  scope: 'all',\n  limit: 5,\n})\n```\n\nFull client docs in [`packages/client/README.md`](./packages/client/README.md).\n\n## Tools\n\nThe hosted server at `https://mcp.onplana.com/mcp` exposes 285 tools,\nspanning projects, tasks, sprints, milestones, earned value, risks,\nissues, governance, change control, timesheets, wikis, whiteboards,\nworkflows and the Microsoft Graph integrations. The exact number a given\nclient sees is smaller, because tools are filtered by the caller's role\nand the organization's plan before the catalog is served.\n\nThe 33 below are the ones worth knowing first, not the whole catalog.\nReads are annotated `readOnlyHint`; writes carry `destructiveHint` so a\nclient can gate them. Every call runs under the calling identity, is\nchecked against that user's permissions and the org's plan, and lands in\nthe audit trail.\n\n**Read** (`readOnlyHint: true`)\n\n- `list_projects`: projects in the org, filterable by status.\n- `get_project`: one project in full, with dates, owner and progress.\n- `list_tasks`: tasks for a project, or across projects.\n- `get_task`: one task with description, assignee, dates and recent comments.\n- `list_my_tasks`: tasks assigned to the calling user.\n- `list_overdue`: tasks past their due date.\n- `list_team_members`: members of a project.\n- `list_org_members`: members of the organization.\n- `list_risks`: risks logged against a project.\n- `find_similar_projects`: past projects resembling a description, for estimating.\n- `search_org_knowledge`: hybrid BM25 and vector search over tasks, projects, wiki pages and comments.\n- `summarize_project`: AI summary synthesized from the live plan.\n- `analyze_project_risks`: AI risk detection across schedule, budget, scope and resources.\n- `generate_status_report`: AI status report from the current schedule and activity.\n- `search`: App Directory adapter, returns `{id, title, snippet?, url?}`.\n- `fetch`: App Directory adapter, returns `{id, title, content, url?, metadata?}`.\n\n**Write, additive** (`destructiveHint: false`)\n\n- `create_project`: create a project.\n- `create_task`: create a task, optionally under a parent.\n- `create_milestone`: add a milestone to a project.\n- `create_comment`: comment on a task, issue or project.\n- `create_sprint_with_tasks`: create a sprint and pull tasks into it.\n- `submit_timesheet`: log hours against a task.\n- `add_project_member`: add an existing org member to a project.\n- `link_dependency`: link two tasks, idempotent via a unique constraint.\n\n**Write, mutating** (`destructiveHint: true`)\n\n- `update_project`: change project fields such as status, dates or budget.\n- `update_task`: change task fields such as status, progress or dates.\n- `bulk_update_tasks`: apply one change across many tasks.\n- `assign_task`: set a task's assignee.\n- `move_task_to_sprint`: move a task into or out of a sprint.\n\n**Leases** (for agents that share a backlog)\n\n- `next_task`: pick the next available task and claim it in one call.\n  Listing and then claiming leaves a gap two agents can both land in.\n- `claim_task`: take an exclusive lease on a specific task.\n- `renew_task_lease`: extend a lease while the work is still running.\n- `release_task`: hand the lease back; completing or blocking a task\n  releases it too, and ending a session releases everything that run holds.\n\nA lease is keyed to the RUN, not to the user. Two sessions of one client\nauthenticate as the same agent persona, so a user-keyed lock would let\none session release the other's work. Leases expire on their own, so a\ncrashed agent frees its task instead of holding it.\n\nDelete tools are not in the default catalog, and destructive operations\nare deny-by-default: an org owner enables them per operation before an\nagent can call them. The ones that can be enabled are recoverable, moving\nto a recycle bin rather than being destroyed. Prefer `update_task` over\ndelete-and-recreate anyway, since Onplana audits every field change and\nkeeps the history.\n\n## Production checklist\n\nThe template + SDK get you running. Add these on top:\n\n- **Per-token rate limiting.** 60–120 req/min per Bearer token;\n  agentic loops are noisier than humans.\n- **Tenant cost cap.** If your tools call paid LLMs, gate dispatch\n  on month-to-date spend. Onplana's deployment uses\n  `aiMonthlyCostCapUsd` with WARN / BLOCK modes.\n- **Audit logging.** Every dispatch should write an audit row\n  tagged with `actorType: 'mcp_agent'` so admins can see what AI\n  agents did in their tenant separately from human activity.\n- **Plan / scope curation.** Don't expose every internal tool.\n  Onplana exposes 21 of 26; the suppressed 5 either need an in-app\n  preview UI, are too risky for unsupervised invocation, or produce\n  oversized payloads.\n- **PREVIEW mode for risky mutations.** Default mutating tools to\n  preview-only on free tiers. Onplana ships this: agents see \"what\n  it would do\" before users explicitly upgrade and re-run.\n- **Idempotency keys.** Hash the canonicalised input + a session\n  id; store as a unique constraint on your audit row. A model\n  retrying the same logical action shouldn't double-create.\n\nEach of those is platform-specific. The template gives you the seam\nwhere they plug in (`Dispatcher.callTool`); your dispatcher\nimplements them however your platform encodes those concepts.\n\n## Compatibility\n\n- Node.js ≥ 20 (for the server template and CI matrix); ≥ 18 for\n  the client (uses ambient `fetch`).\n- `@modelcontextprotocol/sdk@^1.29.0`\n- `express@^4.18.0` or `express@^5.0.0`\n\nTested against:\n\n- Claude Code (plugin marketplace, or `claude mcp add --transport http`)\n- Claude Desktop (Custom Connector)\n- Cursor (`~/.cursor/mcp.json`)\n- ChatGPT custom connectors (where MCP is enabled in your account)\n- Gemini CLI + Gemini Code Assist (`~/.gemini/settings.json`)\n- GitHub Copilot in VS Code (`.vscode/mcp.json`)\n- The official [MCP Inspector](https://github.com/modelcontextprotocol/inspector)\n\n## Install in Claude Code\n\nThe repo doubles as a Claude Code plugin marketplace, so installing is\ntwo commands:\n\n```bash\n/plugin marketplace add Onplana/onplana-mcp-server\n/plugin install onplana@onplana\n```\n\nThen attach the server:\n\n```bash\n/onplana-connect\n```\n\nThat runs `claude mcp add --transport http onplana\nhttps://mcp.onplana.com/mcp` and walks you through the browser sign-in.\nThe MCP server is available on every Onplana plan, including the free\none.\n\nThe plugin ships the two Onplana agent skills, invoked as\n`onplana:<name>`:\n\n| Skill | Use it when |\n|---|---|\n| `onplana-project-planner` | You have a goal or a brief and want an executable plan: a plan document attached to the project, then a task tree with dates, dependencies, owners and test cases. |\n| `onplana-autonomous-agent` | A plan already exists and you want it run: claim a task, work it, record progress and evidence, resolve or hand it back, then take the next one. |\n\nThe plugin manifest deliberately declares no MCP server. A plugin\ndeclares servers in the stdio form (`command`, `args`, `env`), and\nOnplana's is remote and OAuth-authenticated, so `/onplana-connect`\nattaches it at runtime through Claude Code's native HTTP transport\nrather than routing it through a stdio shim.\n\n## Install in Gemini CLI\n\nThe repo ships a `gemini-extension.json` manifest at the root, so\nGemini CLI installs Onplana with one command:\n\n```bash\nexport ONPLANA_PAT=pat_paste-your-token-here  # mint at app.onplana.com/integrations\ngemini extensions install https://github.com/Onplana/onplana-mcp-server\n```\n\nRestart the `gemini` CLI (or reload your VS Code / JetBrains window\nif you're using Gemini Code Assist). The Onplana tools appear in\n`/mcp` and your `GEMINI.md` context picks up the usage hints\nshipped in this repo.\n\n## Contributing\n\nIssues + PRs welcome. The repo is small by design, the goal is for\nthe transport patterns to be obvious, well-tested, and stable.\nMajor-version bumps are reserved for breaking changes to the\nexported `Dispatcher` / `BearerAuth` / handler factory shapes.\nPatches and minors are for prompt-injection containment refinements,\nnew helper utilities, additional test coverage.\n\n## License\n\n[MIT](./LICENSE). © 2026 Onplana\n\n## See also\n\n- **[onplana.com/mcp](https://onplana.com/mcp)**: public docs page\n  for the production Onplana MCP deployment (full tool catalog,\n  setup instructions, security model)\n- **[onplana.com](https://onplana.com)**: Onplana, the PM platform.\n  Cloud-agnostic, AI-native, Microsoft Project Online alternative\n- **[Model Context Protocol specification](https://spec.modelcontextprotocol.io)**: the MCP standard\n- **[Anthropic prompt-injection guidance](https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/overview)**: the security pattern this repo's wrap implements\n",
  "bytes": 14988,
  "sha": "6e334e40d9338f316888bcc62434333c02f8a297310e9601610865d1fbf0b6b2",
  "repo_slug": "onplana/onplana-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_onplana_mcp_server_edbad32c/readme"
}