Connect Cursor

How to add the Penling MCP server to Cursor and use your published plans inside the Cursor agent.

Cursor supports MCP servers natively. Once Penling is added to your Cursor config, the agent can read your published plans, claim actions, and report progress — all from inside the Cursor agent panel.

Prerequisites

Before you start:

• Cursor version 0.45 or later (MCP HTTP support was added in 0.45)
• A Penling account with at least one workspace
• A plan that has been published to MCP (see Publish a plan to MCP)
• The Penling API URL for your deployment (find it under Settings → Integrations → MCP server)

Add Penling to Cursor

Cursor reads MCP server configuration from .cursor/mcp.json in your project root, or from ~/.cursor/mcp.json for user-wide access across all projects.

Create or edit the file:

{
  "mcpServers": {
    "penling": {
      "url": "https://api.penling.app/mcp"
    }
  }
}

Replace https://api.penling.app/mcp with the URL from Settings → Integrations → MCP server in the Penling app.

After saving, reload Cursor (Cmd/Ctrl + Shift + P → "Reload Window") to pick up the new config.

Verify the connection

Open the Cursor agent panel and type:

/mcp

You should see penling listed with a green dot. If it shows an error, check the troubleshooting section below.

Authenticate on first use

Penling uses OAuth 2.0 with PKCE — no API keys to copy, rotate, or accidentally commit. The first time the agent calls a Penling tool, Cursor will:

1. Detect that the Penling MCP server requires authorization
2. Open your browser to the Penling sign-in and consent page
3. Ask you to grant the specs.read and builds.write scopes
4. Redirect back to Cursor, which stores the token securely

You only need to do this once per machine. Tokens refresh automatically when they expire.

Using plans in Cursor Agent

Open the agent panel (Cmd/Ctrl + L) and start with:

What Penling actions are available?

The agent calls list_available_specs and presents a list of unclaimed actions. Pick one, and the agent will:

1. Claim the action (claim_action) — the claim is atomic; no other agent can take it while you hold it
2. Load the brief (get_action_brief) — spec, acceptance criteria, plan approach, and any open clarifications
3. Raise blocking questions in the chat before touching any code
4. Follow TDD — write failing tests first, then implementation
5. Report test results per criterion as they pass (report_test_result)
6. Submit for review when all criteria are green (submit_for_review)

Resuming a session

If you close Cursor and reopen it while an action is in progress, tell the agent:

Resume my claimed action

The agent calls get_action_brief with your action's pid to reload all context, including any clarifications answered since the last session. It does not re-claim — the claim persists across sessions.

Targeting a specific action

If you know the action reference code (e.g. PEN-42), you can target it directly:

Pick up PEN-42

The agent resolves the refCode to a pid and claims it without needing to present the full list first.

Clarifications flow

When the agent hits an ambiguity it cannot resolve from the spec:

1. It calls request_clarification to log the question in Penling
2. It asks you the same question verbatim in the Cursor chat

Answer in the chat. The agent records your answer (answer_clarification) and resumes work. All questions and answers appear in Penling under the action's detail panel, giving reviewers a full decision trail.

Troubleshooting

Penling shows red in /mcp

Cursor cannot reach the MCP endpoint. Check:

• The URL in .cursor/mcp.json is correct (no trailing slash, path ends in /mcp)
• Your network allows outbound HTTPS to the Penling API
• Reload Cursor after editing the config file

"Authorization required" keeps reappearing

The stored token may have been cleared. Remove and re-add the server to reset the OAuth state:

1. Remove the penling entry from .cursor/mcp.json
2. Save and reload Cursor
3. Re-add the entry and reload again — the auth prompt will reappear on the next tool call

Tools not appearing in the agent

Cursor indexes MCP tools at window load. If you added the config while Cursor was already open, reload the window (Cmd/Ctrl + Shift + P → "Reload Window").

"Action already claimed" error

The action is held by another session or team member. Either release it from the other session or from the Penling action detail panel, or choose a different action. Claiming the same action twice always fails with 409.

Agent stops mid-action with no explanation

Check for open clarifications in Penling — the agent may have raised a question that was not surfaced in chat. Open the action detail panel in Penling, answer any open questions there, then tell the agent to resume.