How to connect Onplana to Windsurf
Five steps. Generate a PAT, paste the mcpServers snippet (Windsurf uses serverUrl), refresh Cascade, verify with a tool call. About 5 minutes.
What you can do after: ask Cascade things like “create a project plan for the Q3 launch with weekly milestones,” or “summarize this week’s risks across all active projects,” and Windsurf runs the work directly in Onplana without leaving your editor.
The five steps
- 1
Generate an Onplana connection token
Sign in to Onplana at app.onplana.com. Go to Integrations, then AI agents, then Generate connection (pick the Windsurf tile, or the "Other MCP client" tile). 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 touch anything outside the MCP surface.
- 2
Open the Windsurf Cascade MCP config
In Windsurf, open Settings, then Cascade, then the MCP servers section, and choose "Manage MCPs" then "View raw config". This opens mcp_config.json. On macOS and Linux it lives at ~/.codeium/windsurf/mcp_config.json; on Windows under your user profile's .codeium\windsurf folder. If the file is empty, start it with {}.
- 3
Paste the Onplana MCP server config
Add an "onplana" entry under the "mcpServers" key. The full config: {"mcpServers": {"onplana": {"serverUrl": "https://mcp.onplana.com/mcp", "headers": {"Authorization": "Bearer pat_paste-your-token-here"}}}}. Windsurf uses the key "serverUrl" for remote HTTP servers (not "url"). Replace pat_paste-your-token-here with the token from step 1, then save.
- 4
Refresh Cascade
Back in the MCP servers panel, click "Refresh" (the circular arrow) so Cascade re-reads the config and performs the MCP handshake. The onplana server should show a green status and an "available tools" count.
- 5
Verify the connection
In Cascade, ask: "list my Onplana projects". Windsurf calls Onplana's list_projects tool and shows the result. If you see an error: re-check the token, confirm the key is "serverUrl" (not "url"), confirm your Onplana plan tier includes MCP (PRO and above), and confirm the JSON is valid.
~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"onplana": {
"serverUrl": "https://mcp.onplana.com/mcp",
"headers": {
"Authorization": "Bearer pat_paste-your-token-here"
}
}
}
}How to verify it’s working
Open Cascade 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.”
Cascade shows the tool call before running it, so you can review what data is read or written. Mutations on free or starter plans return a PREVIEW result by default (not committed until you approve); PRO and above commit immediately.
Frequently asked
Which Onplana plan includes MCP access?
MCP access is included with the PRO plan ($12/seat/month, $10 annual) and above. FREE and STARTER plans do not include MCP. You can change plans at any time from app.onplana.com/billing.
Why does Windsurf use "serverUrl" instead of "url"?
That is Windsurf's config schema for remote MCP servers over HTTP. Claude Desktop and Cursor use "url"; Windsurf Cascade uses "serverUrl". The rest of the entry (the onplana server name and the Authorization header) is identical. Using "url" by mistake is the most common reason a Windsurf connection silently fails to appear.
Is Windsurf MCP support stable?
Windsurf ships Cascade MCP support as a preview feature. The Onplana connection works today (Windsurf resolves to the WINDSURF provider and gets the full read plus create plus update tool surface), but Windsurf's MCP UI and config schema can change between releases. Check docs.windsurf.com if the settings move, and keep the same onplana server entry.
What tools does Windsurf get access to?
The same catalog every MCP client sees: reads (list_projects, get_project, list_tasks, list_my_tasks, list_overdue, list_risks, search_org_knowledge, summarize_project, generate_status_report), writes (create_project, create_task, update_task, assign_task, create_milestone, create_comment, bulk_update_tasks, create_sprint_with_tasks, link_dependency), and the governance, change-control, compliance, document, and workflow surfaces. Plan tier gates some tools; see onplana.com/mcp for the full catalog.
Can Windsurf delete projects or tasks via MCP?
No. Onplana does not expose delete_* tools through MCP by design. Updates are reversible via the audit log; deletes would not be. Soft-delete via an update_task status change is the closest available primitive.
Where do I revoke the connection?
Onplana, then Integrations, then AI agents, then tap the token row and Revoke. It takes effect immediately; Windsurf's next tool call returns 401. Audit logs in OrgSettings, then Security show every action the token took.