Pylon

Pylon is an AI-to-human review bridge. AI agents push proposed plans and code diffs via MCP; humans review, comment, and approve via a rich web editor.

MCP Tools

Tool Purpose

push_plan

Push a plan for human review. Auto-creates doc + project + version.

pull_plan

Pull reviewed content with decisions and feedback.

push_code_review

Push file diffs for side-by-side code review.

pull_code_feedback

Pull line-specific review comments grouped by file.

list_documents

List documents, filter by title or project.

list_versions

List version snapshots for a document.

use_document

Switch session's current document context.

update_project

Update project description or rename.

release_document

Release session lock on a document.

See references/tools-plan.md , references/tools-code-review.md , and references/tools-management.md for full parameter docs.

Setup

Add Pylon's MCP server to your agent config. See references/setup.md for per-agent instructions.

Claude Code (.mcp.json ):

{ "mcpServers": { "pylon": { "type": "streamable-http", "url": "https://your-pylon-instance.com/api/mcp", "headers": { "Authorization": "Bearer YOUR_TOKEN" } } } }

Generate a token at Settings > Auth Tokens in the Pylon web UI.

Golden Rule

New user request = new project. Always omit document_id on the first push. The server auto-creates a fresh document every time you call push_plan without document_id . Never look up or reuse document IDs from previous conversations or tasks.

Key Principles

• Native MCP calls only. Never write scripts or temp files to interact with Pylon.

• Always set source . Identify yourself (e.g. "claude-code", "backend-dev") so the human knows which agent produced each document.

• Always set context . Summarize your conversation — helps the web UI's AI make better suggestions.

• New task = omit document_id . push_plan without document_id always creates a new document. Only pass document_id when re-pushing to the same document within the same task after receiving feedback.

• Session memory. After a push, the session remembers the current document for subsequent pulls.

Quick Workflow

1. push_plan(plan="...", source="claude-code", group="my-project", context="...") → Creates NEW document + project, returns document_id + URL → NEVER pass document_id here — let the server create a fresh document
2. Human reviews, comments, edits at the URL
3. pull_plan() → Returns reviewed content, decisions, plain_text
4. Proceed with the approved plan
5. If human requests changes: push_plan(document_id="<id-from-step-1>", plan="...", context="Updated based on feedback...") → Only now pass document_id to update the SAME document

See references/plan-workflow.md for re-push, versioning, and advanced patterns. See references/code-review-workflow.md for the code review lifecycle. See references/multi-agent-teams.md for team/swarm coordination.

Core Concepts

• Projects group related documents via the group param. Auto-created, session-sticky. See references/projects-and-sessions.md .

• Session locking prevents terminal session conflicts (30-min TTL). See references/projects-and-sessions.md .

• Web editing guard blocks terminal pushes while a human is editing (5-min TTL). Human is never locked out.

• Code reviews use side-by-side Monaco diffs with line-specific threaded comments. See references/code-review-workflow.md .