MCP overview

How Penling uses the Model Context Protocol to publish plans to coding agents, and what the agent receives when it connects.

Penling uses the Model Context Protocol (MCP) to bridge the gap between a completed plan and a coding agent that executes it. When you publish a plan to MCP, your agent can read the full spec, work through focus areas in sequence, and raise clarifications back into Penling — all without leaving its native environment.

What MCP does

MCP is an open standard for giving AI agents structured access to external data and tools. Penling acts as an MCP server: it exposes your published plans as structured resources that any MCP-compatible client can read and act on.

The result is a tight, traceable loop:

1. You write and refine the spec in Penling
2. You publish the plan to the MCP server
3. Your agent connects to the MCP server and reads the plan
4. The agent works through focus areas, raising clarifications as needed
5. Clarifications appear in Penling for you to answer
6. The agent re-reads the updated spec and continues

What the agent receives

When the agent connects to the Penling MCP server, it has access to:

• The full plan — phases, focus areas, dependencies, effort estimates
• Each focus area's four-part spec — definition, results, boundaries, notes
• The initiative's goals — so the agent understands the intent behind the spec
• Open clarifications — questions raised but not yet answered, so the agent doesn't unknowingly duplicate them

The agent does not have access to other workspaces, other initiatives it hasn't been given access to, or historical versions of specs (only the current version).

Supported agents

Penling works with any MCP-compatible coding agent. Currently validated integrations:

• Claude Code (Anthropic)
• Cursor
• Any custom agent built on the MCP standard

Security model

Penling uses OAuth 2.0 with PKCE to authenticate MCP connections — the same flow used by tools like GitHub CLI and Vercel CLI. There are no API keys to manage or rotate.

When your agent first connects, it opens a browser where you sign in to Penling and grant two scopes:

• specs.read — read published plans, focus areas, and actions
• builds.write — claim actions, report progress, raise clarifications, and submit for review

The resulting token is tied to your user identity and expires after one hour. Your MCP client (Claude Code, Cursor) re-authenticates automatically when it expires — you only see the browser prompt once per machine.

The token does not grant access to workspace settings, member data, billing, or any initiative you have not been given access to.