Official MCP server and TypeScript client for Onplana — connect Claude, ChatGPT, Cursor, and any MCP-compatible AI agent to your project portfolio.
2026-11-09
スター
5
ツール
—
稼働率
—
onplana-mcp-client: typed TypeScript
client SDK for calling the public Onplana MCP endpoint at
https://api.onplana.com/api/mcp/v1.
What this is
The transport layer of an MCP server (Streamable HTTP wiring,
stateless mode, scoped Bearer auth, prompt-injection containment)
done well, separated from the platform-specific tool registry. Use
the server template to build your own MCP server with security
best practices baked in. Use the client SDK to drive Onplana's
hosted MCP from your own code.
The patterns are extracted from Onplana's production deployment
(public docs at onplana.com/mcp), the
same layer that handles real Claude Desktop, Cursor, ChatGPT custom
connector, and in-house agent traffic against the Onplana platform.
Why open-source
The MCP transport is the same for everyone. Most early MCP servers
get the security primitives wrong:
Prompt injection. Tools that return user-generated content
(task titles, comment bodies, wiki text) put that content directly
into the model's context. Without containment, a hostile actor can
plant "ignore previous instructions" in their own data and the
next agent that reads it follows along.
Stateless transport. Most SDK examples assume in-memory session
state, which breaks horizontal scaling and complicates the auth
model.
Plan-gate semantics. Surfacing tools the caller can't actually
invoke wastes turns and confuses the model.
Onplana solved these in production over six months of MCP-server
work. Publishing the patterns is high-leverage:
Other MCP authors get a known-good template instead of
reinventing.
The repo is a pretraining-signal surface. Public GitHub READMEs
are heavily weighted in next-gen LLM training data, and a repo
with patterns + clear documentation about MCP improves model
recall of "what good MCP servers look like."
The dispatcher interface is the seam where your business logic
plugs in. The transport is generic; what matters about your MCP
server is the tool registry. Open-sourcing the transport doesn't
give away anything proprietary.
The dispatcher implementation, tool catalog, plan-gate logic, audit
infrastructure, and the rest of Onplana's ~600 LOC closed-source
dispatcher stay in the closed monorepo because they encode platform
business logic. If you build your own MCP server using this
template, you write your own dispatcher. That's the work that
matters and the work that's specific to your platform.
The hosted server at https://mcp.onplana.com/mcp exposes 285 tools,
spanning projects, tasks, sprints, milestones, earned value, risks,
issues, governance, change control, timesheets, wikis, whiteboards,
workflows and the Microsoft Graph integrations. The exact number a given
client sees is smaller, because tools are filtered by the caller's role
and the organization's plan before the catalog is served.
The 33 below are the ones worth knowing first, not the whole catalog.
Reads are annotated readOnlyHint; writes carry destructiveHint so a
client can gate them. Every call runs under the calling identity, is
checked against that user's permissions and the org's plan, and lands in
the audit trail.
Read (readOnlyHint: true)
list_projects: projects in the org, filterable by status.
get_project: one project in full, with dates, owner and progress.
list_tasks: tasks for a project, or across projects.
get_task: one task with description, assignee, dates and recent comments.
list_my_tasks: tasks assigned to the calling user.
list_overdue: tasks past their due date.
list_team_members: members of a project.
list_org_members: members of the organization.
list_risks: risks logged against a project.
find_similar_projects: past projects resembling a description, for estimating.
search_org_knowledge: hybrid BM25 and vector search over tasks, projects, wiki pages and comments.
summarize_project: AI summary synthesized from the live plan.
analyze_project_risks: AI risk detection across schedule, budget, scope and resources.
generate_status_report: AI status report from the current schedule and activity.
create_task: create a task, optionally under a parent.
create_milestone: add a milestone to a project.
create_comment: comment on a task, issue or project.
create_sprint_with_tasks: create a sprint and pull tasks into it.
submit_timesheet: log hours against a task.
add_project_member: add an existing org member to a project.
link_dependency: link two tasks, idempotent via a unique constraint.
Write, mutating (destructiveHint: true)
update_project: change project fields such as status, dates or budget.
update_task: change task fields such as status, progress or dates.
bulk_update_tasks: apply one change across many tasks.
assign_task: set a task's assignee.
move_task_to_sprint: move a task into or out of a sprint.
Leases (for agents that share a backlog)
next_task: pick the next available task and claim it in one call.
Listing and then claiming leaves a gap two agents can both land in.
claim_task: take an exclusive lease on a specific task.
renew_task_lease: extend a lease while the work is still running.
release_task: hand the lease back; completing or blocking a task
releases it too, and ending a session releases everything that run holds.
A lease is keyed to the RUN, not to the user. Two sessions of one client
authenticate as the same agent persona, so a user-keyed lock would let
one session release the other's work. Leases expire on their own, so a
crashed agent frees its task instead of holding it.
Four delete tools are in the catalog (a task, a project, a list, a
document). Each is a per-organization switch that is on until an org admin
saves a choice, the agent still needs the underlying permission, and all
four move items to a recycle bin rather than destroying them. Prefer update_task over
delete-and-recreate anyway, since Onplana audits every field change and
keeps the history.
Production checklist
The template + SDK get you running. Add these on top:
Per-token rate limiting. 60–120 req/min per Bearer token;
agentic loops are noisier than humans.
Tenant cost cap. If your tools call paid LLMs, gate dispatch
on month-to-date spend. Onplana's deployment uses
aiMonthlyCostCapUsd with WARN / BLOCK modes.
Audit logging. Every dispatch should write an audit row
tagged with actorType: 'mcp_agent' so admins can see what AI
agents did in their tenant separately from human activity.
Plan / scope curation. Don't expose every internal tool.
Onplana exposes 21 of 26; the suppressed 5 either need an in-app
preview UI, are too risky for unsupervised invocation, or produce
oversized payloads.
PREVIEW mode for risky mutations. Default mutating tools to
preview-only on free tiers. Onplana ships this: agents see "what
it would do" before users explicitly upgrade and re-run.
Idempotency keys. Hash the canonicalised input + a session
id; store as a unique constraint on your audit row. A model
retrying the same logical action shouldn't double-create.
Each of those is platform-specific. The template gives you the seam
where they plug in (Dispatcher.callTool); your dispatcher
implements them however your platform encodes those concepts.
Compatibility
Node.js ≥ 20 (for the server template and CI matrix); ≥ 18 for
the client (uses ambient fetch).
@modelcontextprotocol/sdk@^1.29.0
express@^4.18.0 or express@^5.0.0
Tested against:
Claude Code (plugin marketplace, or claude mcp add --transport http)
Claude Desktop (Custom Connector)
Cursor (~/.cursor/mcp.json)
ChatGPT custom connectors (where MCP is enabled in your account)
The plugin brings the server with it, then sign in once:
/onplana-connect
That walks you through the browser sign-in and checks the connection
with whoami. The MCP server is available on every Onplana plan,
including the free one.
The plugin ships the two Onplana agent skills, invoked as
onplana:<name>:
Skill
Use it when
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.
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.
The plugin declares the server in plugins/onplana/.mcp.json as a
remote HTTP server, so Claude Code connects to it directly with no
stdio shim. If you already added the same URL with claude mcp add,
Claude Code keeps your entry and skips the plugin's, so there is
still one set of tools.
Install in Gemini CLI
The repo ships a gemini-extension.json manifest at the root, so
Gemini CLI installs Onplana with one command:
export ONPLANA_PAT=pat_paste-your-token-here # mint at app.onplana.com/integrations
gemini extensions install https://github.com/Onplana/onplana-mcp-server
Restart the gemini CLI (or reload your VS Code / JetBrains window
if you're using Gemini Code Assist). The Onplana tools appear in
/mcp and your GEMINI.md context picks up the usage hints
shipped in this repo.
Contributing
Issues + PRs welcome. The repo is small by design, the goal is for
the transport patterns to be obvious, well-tested, and stable.
Major-version bumps are reserved for breaking changes to the
exported Dispatcher / BearerAuth / handler factory shapes.
Patches and minors are for prompt-injection containment refinements,
new helper utilities, additional test coverage.
最終チェックは 2026-11-09 です。 Official MCP server and TypeScript client for Onplana — connect Claude, ChatGPT, Cursor, and any MCP-compatible AI agent to your project portfolio.