MCP & agents6 min read · Updated Jun 2026

Connect Claude Code

Step-by-step guide to connecting Claude Code to the Penling MCP server and running your first agent-driven build.

Claude Code connects to Penling over HTTP using the Model Context Protocol. Once connected, it can read your published plans, claim actions, raise clarifications, and report progress — all from inside the terminal, without switching context.

Prerequisites

Before you start:

Claude Code installed and authenticated (claude --version should print a version number)
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)

Configure the MCP connection

MCP servers are declared in a JSON config file that Claude Code reads at startup. The file can live at two levels:

Scope	Location
User-wide (all projects)	`~/.claude.json`
Project-only	`.mcp.json` in the project root

Add a penling entry under mcpServers:

json

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

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

Project vs user scope — Use the project-level .mcp.json if you want team members to share the same config via version control (commit the file, but never commit tokens). Use ~/.claude.json if you work across multiple repositories that all use the same Penling workspace.

Authenticate on first use

Penling uses OAuth 2.0 with PKCE — the same secure flow used by GitHub CLI, Vercel CLI, and other developer tools. You do not need to manage tokens manually.

The first time Claude Code calls a Penling tool in a session, it will:

Detect the WWW-Authenticate header from the MCP server
Open your browser to the Penling authorization page
Ask you to sign in and grant the specs.read and builds.write scopes
Redirect back to a local callback and store the token in your OS keychain

You will see output like:

Opening browser for Penling MCP authorization…
Waiting for callback on http://127.0.0.1:PORT/callback
✓ Authorized. Token stored.

After that, Claude Code reuses the stored token until it expires (1 hour). Re-authentication is silent and automatic on the next tool call after expiry.

Running your first build

With the connection established, start Claude Code in your repository:

bash

claude

Then prompt it to look for available work:

What Penling actions are available?

Claude Code calls list_available_specs, presents the available actions, and asks you to pick one before doing anything else. The flow from there:

You pick an action — Claude Code calls claim_action to atomically reserve it
Brief loads — get_action_brief returns the full spec, acceptance criteria, and any open clarifications
Clarifications resolved — if there are open questions, Claude Code raises them in chat before writing any code
Work begins — Claude Code follows TDD: failing tests first, then implementation
Progress reported — update_progress and report_test_result calls keep the Penling canvas live as work proceeds
Submitted — submit_for_review locks the action and creates a review record in Penling

What the agent can do

Once connected, Claude Code has access to the following Penling tools:

Tool	What it does
`list_available_specs`	Lists all published specs with their claimable actions
`get_spec`	Fetches a single spec's full detail
`claim_action`	Atomically claims an action — only one agent can hold it at a time
`get_action_brief`	Loads the full implementation brief for a claimed action
`get_attachment_url`	Refreshes a signed URL for a file attached to the spec
`release_action`	Releases a claimed action back to the pool
`update_progress`	Reports a milestone and heartbeats the claim
`request_clarification`	Records a blocking question against the action
`answer_clarification`	Records the answer to a previously raised question
`report_test_result`	Records a per-criterion test outcome (pass or fail)
`report_commit`	Records a git commit against the action
`submit_for_review`	Submits the completed action for human review
`resubmit_for_review`	Updates a submission after addressing review feedback

Clarifications flow

When Claude Code encounters an ambiguity it cannot resolve from the spec alone, it will:

Call request_clarification to log the question in Penling
Ask you the same question verbatim in the chat

You answer in the chat. Claude Code then calls answer_clarification to record your response, and resumes the work.

All open and answered clarifications appear in Penling under the action's detail panel. This gives reviewers a full audit trail of the decisions made during implementation.

Troubleshooting

"No MCP servers found" or tools not appearing

Check that your config file is valid JSON and that Claude Code is reading the right file:

bash

claude mcp list

If penling does not appear, verify the file path and JSON syntax. A trailing comma is a common mistake.

Browser does not open for authentication

Some environments block automatic browser launches. Run:

bash

claude mcp auth penling

This prints the authorization URL so you can open it manually and complete the flow.

"invalid_token" error mid-session

Tokens expire after 1 hour. Claude Code re-authenticates automatically, but if the error persists, clear the stored token:

bash

claude mcp auth penling --reset

Then start a new session to trigger a fresh browser flow.

"Action already claimed" (409)

Another session or team member holds the action. Either wait for it to be released, or pick a different action from list_available_specs. Do not call claim_action again — it will continue to fail with 409.

Plan not visible after publishing

list_available_specs only returns plans in published state. If you republished after spec changes, the plan should appear immediately. If it does not, verify the plan's status in Penling under the plan view.