How-to · About 5 minutes

How to connect Onplana to Claude Desktop

Five steps. Generate a PAT, paste the config snippet, restart Claude Desktop, verify with a tool call. Total time about 5 minutes.

What you’ll be able to do after: ask Claude things like “create a project plan for the Q3 launch with weekly milestones,” or “summarize this week’s risks across all active projects,” and Claude runs the work directly in Onplana.

Open Onplana → Settings → Agents Download Claude Desktop

The five steps

  1. 1

    Generate an Onplana connection token

    Sign in to Onplana at app.onplana.com. Go to Settings → Agents → Connect agent, pick the Claude Desktop tile (or Custom MCP client), choose Personal access token, then Generate token + show connection snippet. Copy the personal access token (it starts with `pat_`). The token has MCP_AGENT scope only. It can call MCP tools but cannot create other tokens, modify billing, or anything outside the MCP surface.

  2. 2

    Open Claude Desktop config

    In Claude Desktop, click Settings → Developer → Edit Config. This opens claude_desktop_config.json in your default editor. On macOS this lives at ~/Library/Application Support/Claude/claude_desktop_config.json. On Windows: %APPDATA%\Claude\claude_desktop_config.json. If the file is empty or doesn't exist, create it with `{}`.

  3. 3

    Paste the Onplana MCP server config

    Add an "onplana" entry under the "mcpServers" key. The full config: {"mcpServers": {"onplana": {"url": "https://mcp.onplana.com/mcp", "headers": {"Authorization": "Bearer pat_paste-your-token-here"}}}}. Replace pat_paste-your-token-here with the token you copied in step 1. Save the file.

  4. 4

    Restart Claude Desktop

    Quit Claude Desktop completely (Cmd+Q on macOS, full close on Windows). Reopen it. The Onplana tool should appear in the tools picker.

  5. 5

    Verify the connection

    In a new conversation, ask: "list my Onplana projects". Claude calls Onplana's list_projects tool and shows you the result. If you see an error: re-check the token, and confirm the config file is valid JSON.

claude_desktop_config.json

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

How to verify it’s working

Open a new Claude Desktop conversation and try any of:

  • “List my Onplana projects.”
  • “What’s overdue in my Onplana account?”
  • “Create an Onplana task in project X called ‘Migrate Postgres to Aurora’.”
  • “Generate a status report for project Y.”

Claude shows you the tool call inline before running it, so you can review what data is being read or written. Mutations apply on every plan; on Free some write actions carry a monthly cap (none from Professional up), and the agent can request a non-committing preview of a call via its dryRun option.

Frequently asked

Which Onplana plan includes MCP access?

MCP access is included on every plan, including Free. The number of concurrent agent connections scales with your plan (Free 2, Professional 3, Business 5, Enterprise 10, Enterprise+ unlimited), and your AI token balance (a monthly allowance on paid plans, a one-time bonus on Free, plus purchased credit) is what bounds actual AI usage. You can change plans at any time from app.onplana.com/billing.

Is OAuth available as an alternative to PAT?

Yes. Onplana is listed in Claude's Connectors directory: in Claude Desktop (or claude.ai) open Settings, find Connectors, browse the directory, choose Onplana and approve the browser sign-in, with nothing to paste. Underneath it is OAuth 2.1 with PKCE, and Onplana publishes RFC 9728 + RFC 8414 discovery metadata at https://mcp.onplana.com/.well-known/oauth-protected-resource and oauth-authorization-server. The PAT-paste flow described here is for when you want the config file; OAuth is for users who prefer not to manage long-lived tokens.

What tools does Claude get access to?

346 tools spanning reads (e.g. list_projects, get_project, list_tasks, list_my_tasks, list_overdue, list_risks, search_org_knowledge, summarize_project, analyze_project_risks, generate_status_report), writes (e.g. create_project, create_task, update_task, assign_task, create_milestone, create_comment, bulk_update_tasks, create_sprint_with_tasks, submit_timesheet, link_dependency, move_task_to_sprint), and the full governance, change-control, compliance, document, and workflow surfaces. Plan tier gates some tools; see onplana.com/mcp for the full catalog.

Can Claude delete projects or tasks via MCP?

Yes, recoverably, unless an admin has turned it off. The destructive tools over MCP are delete a task, a project, a list, or a document. Each is a per-workspace switch that is on until an admin saves a choice, and the caller still needs the permission it would need anyway. All of them soft-delete to the recycle bin, and a deleted task or project is captured with its whole subtree and restores under the original ids, so dependencies and hierarchy survive. Sprints, milestones, epics and goals have no delete tool over MCP at all.

Can I use Claude Code (CLI) instead of Claude Desktop?

Yes. Claude Code ships with built-in MCP support. One-liner install: `claude mcp add onplana --transport http https://mcp.onplana.com/mcp`. Claude Code triggers OAuth on first tool call (no PAT paste needed), opens a browser to sign in to Onplana, runs the consent flow, then any subsequent `claude` session in that project sees the Onplana tool catalog. To use a PAT instead of OAuth, append `--header "Authorization: Bearer pat_…"` to the add command. Verify with `claude mcp list`. Works on macOS, Linux, and WSL on Windows.

Where can I revoke the connection?

In Onplana, Settings → Agents → Connections lists every connection, personal access tokens and browser sign-ins alike: choose Revoke on the row. It takes effect immediately; the next Claude tool call returns 401 and Claude prompts you to reconnect.

What happens if my token leaks?

Revoke it immediately (see above). Mint a new one in the same panel. The compromised token stops working on its next call. On the Enterprise plan and up, an organization owner or admin sees every call the leaked token made on the Audit Logs page, under Agent Activity, so you can review what the attacker may have seen or changed.

Does this work on Linux?

Claude Desktop is currently macOS and Windows only. On Linux: use a third-party MCP client like the official MCP Inspector (npx @modelcontextprotocol/inspector), Cursor (Linux supported), or wire the Onplana connection into a local agent script using Onplana's typed TypeScript client SDK.

Related