Connect an external AI agent (MCP)

Onplana exposes a Model Context Protocol (MCP) endpoint, so AI coding agents and assistants, Claude Code, Claude Desktop, Cursor, Codex, Windsurf, and any other MCP client, can connect to your organization and work with your projects directly. A connected agent becomes a real member of your organization (an agent persona) that can be assigned tasks like any teammate.

The end result: you can be writing code in Cursor, ask “what is blocking the Payments project”, and your agent finds the answer in Onplana without you switching tabs. Or you assign a task to your agent, walk away, and come back to a posted comment with a draft you can review.

Quick reference

Endpoint	URL	Authentication
Authenticated (your org)	https://mcp.onplana.com/mcp	Personal access token (Bearer)
Public docs	https://mcp.onplana.com/docs	None, read-only

How it works

The Model Context Protocol is a small open standard (built by Anthropic and adopted by Claude, Cursor, Codex, Windsurf, and others) for letting an AI agent call a set of tools on a remote server. Onplana publishes each of its core operations (find a project, list tasks, post a comment, update a status, create a sprint) as one of those tools. Your agent discovers them on connect and decides which ones to call as you chat.

You generate a personal access token scoped for agent use, then paste a small config snippet into your agent. From then on, the agent talks to Onplana’s MCP endpoint using that token and can list, create, and update work, all within the permissions you grant.

• MCP endpoint: https://mcp.onplana.com/mcp
• Authentication: a personal access token, sent as a Bearer token.
• Transport: Streamable HTTP (the modern MCP transport, supported by every current MCP client).

Tested clients

Onplana is regularly tested with:

• Claude Code (CLI) and Claude Desktop
• Cursor
• Codex (OpenAI)
• Windsurf

Any other MCP client that speaks Streamable HTTP should work too; see 2d. Other MCP clients on the main MCP overview page for the smoke-test command.

Connect an agent

1. Open People and select Connect Agent (also available from Integrations → AI agents).
2. Pick your agent, Claude Code, Cursor, Codex, Windsurf, and others, and give the connection a label so you can recognize it later.
3. Select Generate token. Onplana mints a token scoped for agent use.
4. Copy the token and the provided config snippet into your agent. The modal gives you copy buttons for the token, the MCP endpoint, and the full snippet, plus a one-line claude mcp add command for Claude.
5. Save the token now. For security it is shown only once; if you lose it, revoke the connection and create a new one.

Caution

The token is displayed a single time. Store it in your agent’s config or a password manager before closing the dialog. There is no way to view it again afterwards.

Example: Claude Code in one line

If you use Claude Code (or any client that supports the claude mcp add form), the entire setup after step 3 is:

claude mcp add onplana --transport http https://mcp.onplana.com/mcp \
  --header "Authorization: Bearer pat_paste-your-token-here"

Claude Code will discover the available tools on the next conversation and surface them as it works.

Example: Cursor and Claude Desktop (JSON)

Open your client’s MCP settings and add an entry like this. The Connect Agent modal in Onplana provides a copy-paste snippet that already has your token interpolated, so you usually do not type this by hand:

{
  "mcpServers": {
    "onplana": {
      "transport": { "type": "http", "url": "https://mcp.onplana.com/mcp" },
      "headers":   { "Authorization": "Bearer pat_paste-your-token-here" }
    }
  }
}

Restart your client so it picks up the new server. The Onplana tools appear in the tool picker, prefixed with the connection label.

Verify the connection

After connecting, ask your agent something concrete that only Onplana can answer, for example “List my open tasks across all projects.” You should see the agent invoke a list_tasks tool, then summarize the result. If the response is generic (“I cannot access your projects”), the token is missing or the server entry is not loaded; restart the client and re-check the config.

What the agent can do

A connected agent acts within the permissions of the token you created. Concretely it can:

• Find projects, tasks, sprints, milestones, issues, proposals, and people across the projects it has access to.
• Read task descriptions, comments, attachments, recent activity, and AI-generated risk reports.
• Write by creating and updating tasks (status, priority, assignee, dates, custom fields), posting comments, capturing baselines, and attaching files.
• Coordinate by moving work between sprints or epics, linking dependencies, and proposing schedule changes for human review.

Everything it does is recorded in the activity log and attributed to its agent persona, so you always know what was done by an agent versus a person. If a particular operation would exceed the agent’s permissions (for example, deleting a project the token cannot reach), the tool returns a clean error and the agent reports it back to you.

Tip

You can delegate a task to an agent directly from any task view, and Onplana will mention the agent persona on the task. See Assign work to an agent for the full handoff workflow.

Try the docs without an account

Alongside the authenticated server, Onplana publishes a public, no-account MCP server that exposes the documentation you are reading right now. It is read-only, has no access to any Onplana organization, and is useful for letting an agent look up “how do I do X in Onplana” without you having to create a token first.

Add it to a desktop or IDE agent in one line:

claude mcp add onplana-docs https://mcp.onplana.com/docs

The public server provides two tools: search_docs (keyword search over every published article) and read_docs_page (fetch one full article as markdown). It is rate limited per IP and serves only documentation content, so it is safe to share or to point a new teammate at while they evaluate Onplana. To act inside your organization (create tasks, run workflows, post comments), use the authenticated server above.

Managing connections

• See and revoke connected agents in Settings → Agents. Every active connection lists its label, the agent it belongs to, when it last called the server, and a revoke button.
• Scope the token so an agent only touches the work you intend. The Connect Agent modal lets you pick which projects the token can reach; the agent cannot see anything outside that set.
• Expiry: tokens expire automatically (90 days by default). Onplana emails you before expiry so you can rotate cleanly.
• Rotate by minting a fresh connection, updating your client’s config, and revoking the old one. Use a new label so you can tell them apart in the audit log.
• Audit: every tool call is recorded in Logs → Activity, with the connection label, the tool called, and the result. If you need a paper trail for a security or compliance review, that is the place.

Security model in one minute

• A token only gives the agent permissions you already have. An agent cannot do anything in Onplana that you could not do as a member.
• Org admins can disable agent connections org-wide at any time from Org Settings → AI agents (a kill switch for incident response).
• The MCP transport is HTTPS-only and rate-limited per token, so a runaway agent cannot accidentally flood the API.

Want the agent to behave like an experienced PM out of the box? See Install the Onplana agent skills, two short, portable instruction files that teach a connected agent how to plan and run Onplana projects.

Curious what the MCP server can do beyond this setup? The MCP overview on the main site covers supported clients and example workflows.

Troubleshooting

“401 Unauthorized” or the agent says it cannot reach Onplana The token is missing, mistyped, or revoked. Re-check the Authorization: Bearer <token> header in your client’s config, and confirm the connection still appears as active in Settings → Agents.

No Onplana tools appear in my client The client did not load the server entry. Restart the client after saving the config. In Claude Code, run claude mcp list to confirm onplana is present; in Cursor and Claude Desktop, check the MCP settings panel for a green status indicator next to onplana.

The agent only sees some of my projects The token is project-scoped. Open Settings → Agents, edit the connection, and add the missing projects. The change takes effect on the agent’s next tool call; no reconnect needed.

“Tool dispatch failed” or a 5xx response Try the same request again; this is usually transient. If it persists, copy the correlation id from the error message and open a support ticket; that id pivots straight to the structured logs.

My agent’s actions are not showing under its name Activity is attributed by token, so confirm the agent is calling tools with its own connection (not yours). The agent persona shows in the sidebar under People → Agents.

FAQs

Is this the same as the in-app AI assistant? No. The in-app assistant runs inside Onplana and uses the same data, but it is bound to the browser. The MCP connection lets an external agent (running in your editor, terminal, or a hosted runner) reach the same data through standard tool calls. You can use both, and many teams do: the in-app assistant for one-off questions while you work in the app, the external agent for longer-running work while you stay in your editor.

What is an agent persona? When an agent first connects, Onplana provisions it as a member of your organization so it can be assigned tasks and show up in activity. It is clearly marked as an agent, not a person, with a small badge next to its name. The persona is what makes attribution possible across views; you can mention it (@your-agent) on tasks and comments.

Do I need to keep my computer running for the agent to work? The agent runs wherever you run it (your editor, terminal, or a hosted runner). Onplana responds to its requests; it does not run the agent for you. If you close your laptop, the agent stops; reopen it and the agent picks up where it left off.

Can multiple people share one agent connection? You can, but it is not recommended. Tokens audit per connection, not per person, so shared tokens make it hard to tell who did what. Each teammate using an agent should mint their own connection, even for the same agent (different labels).

Can I run more than one agent at once? Yes. There is no limit on the number of active connections per user beyond the per-token rate limits. Many teams run a Claude Code connection on their laptop and a Cursor connection on their desktop under separate labels.

What about hosted agents (CI, automation pipelines)? Mint a separate connection labelled for the runner (for example build-bot-ci), scope it to the project the runner needs, and rotate it on the same cadence as your other CI secrets. Treat it like any service account.

Which plan is required? None. Agent connections are available on every plan, including Free. The number of agent connections scales with your plan (Free 2 concurrent, Starter 2, Pro 3, Business 5, Enterprise 10, Enterprise+ unlimited), and the AI token balance (your one-time bonus plus any purchased credit) is what bounds actual AI usage. The public docs server (above) has no plan requirement.