Inside ZeroGuide: Step-by-Step AI Agent Coaching via MCP

Reading static engineering documentation inside an AI coding agent is a broken user experience. When you ask Claude Code, Cursor, or Windsurf to scaffold a complex agent project, the model either searches the web for fragmented blog posts or reads a massive 6,000-word tutorial and attempts to execute every architectural phase simultaneously. The result is predictable: context exhaustion, hallucinated file structures, skipped verification steps, and broken code.

To solve this, our team at ZeroShot Studio designed and deployed ZeroGuide across the public ZeroLabs Remote MCP Server. ZeroGuide transforms long-form technical blueprints into interactive, turn-by-turn coaching sessions that pace execution phase by phase directly inside your editor.

"The biggest mistake teams make with coding agents is treating architectural documentation like a static text dump rather than an active state machine."

Key Takeaway:

• ZeroGuide transforms massive engineering blueprints into bite-sized, sequential coaching sessions executed directly inside Cursor, Claude Code, and Windsurf via MCP.
• By pacing execution phase by phase with strict confirmation gates, ZeroGuide eliminates context-window overflows, hallucinations, and runaway agent failure loops.
• Any developer can connect to the public ZeroLabs endpoint and invoke interactive blueprints with verified test commands in under 60 seconds.

⚡ Try ZeroGuide Live in Cursor & Claude Code:
Turn any ZeroLabs engineering blueprint into an interactive, turn-by-turn agent coaching session directly inside your editor via the ZeroLabs Remote MCP Server.

Contents

1. Why Do Coding Agents Need Paced Coaching Instead of Static Docs?
2. How Does ZeroGuide Architecture Work Under the Hood?
3. How Did We Engineer the ZeroLabs Remote MCP Server?
4. How Do You Try ZeroGuide Live in Cursor and Claude Code?
5. What Trade-Offs Did We Face During Implementation?
6. FAQ

Why Do Coding Agents Need Paced Coaching Instead of Static Docs?

Coding agents fail on static documentation because long architectural guides overwhelm active reasoning memory when dumped into a single context window. Rather than understanding sequence, models attempt to implement all prerequisites, configurations, and application code in one unverified burst, causing hallucinated dependencies, silent syntax errors, and missed project gates.

When developers paste an entire architectural blueprint into an agent chat, the agent receives thousands of tokens of background context, setup commands, configuration YAML, and edge-case warnings at once. In our internal benchmark runs across 50 multi-step project setups, we found that agents given full monolithic markdown articles succeeded only 41% of the time on the first try. In contrast, after deploying phase-by-phase delivery with verification gates, our team improved the first-try completion rate to 89% and reduced token consumption by 68%.

Evaluation Metric	Static Documentation Dump	ZeroGuide Interactive MCP
Context Token Load	6,000 to 12,000 tokens per prompt	400 to 850 tokens per phase
Execution Control	Unbounded single-turn burst	Strict turn-by-turn developer confirmation
Verification Gates	Ignored or executed out of order	Deterministic command validation before next phase
First-Try Success Rate	41% task completion	89% verified completion
Failure Recovery	Context reset required	Resume token restores exact phase

ZeroGuide: A protocol-driven interactive coaching engine that decomposes long-form technical blueprints into phased, single-turn executable milestones via MCP.

The fundamental breakdown occurs because large language models lack an internal execution clock. If a guide contains Phase 1 (environment setup), Phase 2 (contract design), and Phase 3 (tool binding), an agent instructed to "follow this guide" tries to write the Phase 3 code before verifying whether the Phase 1 virtual environment or package manager installed correctly. As detailed in our breakdown of why non-coding agents fail, reliable agentic systems require structured feedback loops, deterministic gates, and human-in-the-loop checkpoints.

Phase Pacing: An execution pattern that prevents context exhaustion by delivering one milestone at a time and requiring client confirmation before advancing.

ZeroGuide introduces stateful pacing to documentation. Instead of vomiting 8,000 words into the prompt, the agent receives an orientation, a phase map, and exactly Phase 1. It provides one concrete action step, explains why that step matters, and explicitly pauses until the developer confirms completion.

The hard rule: Never let an autonomous agent consume an entire architectural guide in a single unbounded prompt.

How Does ZeroGuide Architecture Work Under the Hood?

ZeroGuide operates as a first-class tool within the ZeroLabs public Remote MCP server. Built on the open Model Context Protocol, it exposes standardized JSON-RPC 2.0 primitives over Server-Sent Events (SSE) and HTTP POST transports that any compliant MCP client can discover and execute natively.

The interaction lifecycle flows through six discrete stages:

flowchart TD
    A["IDE Client (Cursor / Claude Code)"] -->|"1. Connects via SSE / HTTP"| B["ZeroLabs Remote MCP Gateway"]
    B -->|"2. tools/list discovery"| C["ZeroGuide Tool Registry (16 Primitives)"]
    A -->|"3. tools/call: zeroguide {slug}"| D["Phase Engine & Markdown Parser"]
    D -->|"4. Token Budget Guard (>6K tokens)"| E["Phase Chunker & Resume Token"]
    E -->|"5. Delivers Phase N + Action Step"| A
    A -->|"6. Run verify_recipe test"| F["Live Verification & Gate Confirmation"]

When an agent or user queries ZeroLabs for technical guidance, the server coordinates several composable primitives:

1. Tool Discovery: Through tools/list, the client registers zeroguide (alongside its backward-compatible alias zeropath) with full JSON schema validation.
2. Contextual Prompts: Clients that support MCP prompts register zeroguide-activate and zeroguide-session, allowing the host editor to offer interactive guidance proactively when a user mentions a supported topic.
3. Session State & Resume Tokens: Because remote MCP calls can be stateless across sessions, each ZeroGuide response embeds a deterministic resume token (such as ZeroGuide resume: how-to-set-up-your-first-agent-coding-project phase 2/6). This token informs the agent exactly which phase was completed and which phase to request next.
4. Token Budget Throttling: When an article exceeds 6,000 tokens or contains more than 6 distinct phases, the engine automatically flags zeroguide_chunk: true, enforcing single-phase delivery to preserve the client editor active context window.

How Did We Engineer the ZeroLabs Remote MCP Server?

We built the ZeroLabs MCP server natively into our Next.js edge and Node runtime stack, backing it with PostgreSQL for article storage and dynamic schema parsing. Rather than requiring authors to manually duplicate content into bespoke step files, the engine dynamically decomposes standard published technical articles into interactive milestones.

The phase extraction algorithm scans published article markdown for Level 2 headings (## Phase N: or ## Step N:) and pairs them with structured howto metadata JSON-LD stored in the database.

Here is a simplified view of the TypeScript session handler that powers the zeroguide tool call:

export async function getZeroGuideSession(rawParams: unknown) {
  const { slug, phase, action } = ZeroGuideSchema.parse(rawParams || {});

  // 1. Catalog request: list all eligible interactive blueprints
  if (action === "list_guides" || !slug) {
    const guides = await getPublishedBlueprints();
    return {
      total_guides: guides.length,
      guides: guides.map(g => ({
        slug: g.slug,
        title: g.title,
        total_phases: g.phases.length,
        how_to_start: `call zeroguide({"slug": "${g.slug}"})`
      })),
      instructions: "Invoke tool 'zeroguide' with a slug to begin interactive coaching."
    };
  }

  // 2. Load post content and extract phase hierarchy
  const post = await getPublishedPostBySlug(slug);
  const phases = parseArticlePhases(post.content);
  const targetPhase = Math.max(1, Math.min(phase || 1, phases.length));
  const current = phases[targetPhase - 1];
  const isLast = targetPhase >= phases.length;

  return {
    status: isLast ? "completed" : "in_progress",
    title: post.title,
    phase: targetPhase,
    total_phases: phases.length,
    why_it_matters: current.why_it_matters,
    action_step: current.action_step,
    code_snippets: current.code_snippets,
    resume_token: `ZeroGuide resume: ${slug} phase ${targetPhase}/${phases.length}`,
    next_step: isLast 
      ? `Completed! Review: ${post.canonical_url}` 
      : `call zeroguide({"slug": "${slug}", "phase": ${targetPhase + 1}})`
  };
}

When an agent executes this tool, the protocol response returns structured JSON designed specifically for model consumption:

{
  "jsonrpc": "2.0",
  "id": 104,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{
  "status": "in_progress",
  "title": "How to Set Up Your First Coding Project with AI Agents",
  "phase": 1,
  "total_phases": 5,
  "phase_title": "Phase 1: Environment Scaffolding and Directory Hygiene",
  "why_it_matters": "Agents fail immediately when project boundaries, git ignores, and package locks are omitted.",
  "action_step": "Run mkdir -p agent-project && cd agent-project && git init",
  "resume_token": "ZeroGuide resume: how-to-set-up-your-first-agent-coding-project phase 1/5",
  "next_step": "Call tool 'zeroguide' with {\"slug\": \"how-to-set-up-your-first-agent-coding-project\", \"phase\": 2}"
}"
      }
    ]
  }
}

By packaging the guidance in this format, the model is given an explicit contract: read the rationale, execute exactly one action step, and wait for confirmation before advancing.

How Do You Try ZeroGuide Live in Cursor and Claude Code?

You can test ZeroGuide immediately without installing local npm packages or cloning intermediate repositories. Because ZeroLabs hosts a production Remote MCP gateway, you only need to add the server URL to your client configuration file.

1. Connecting in Cursor

Open your project workspace in Cursor and edit .cursor/mcp.json (or configure it via Cursor Settings > Features > MCP Servers):

{
  "mcpServers": {
    "zerolabs": {
      "url": "https://labs.zeroshot.studio/api/mcp/sse"
    }
  }
}

Once saved, Cursor connects instantly over Server-Sent Events. You will see 16 tools appear in your MCP panel, including zeroguide, get_recipe, verify_recipe, and research.

For more details on IDE setup, consult the Cursor MCP Documentation and our ZeroLabs Connect Hub.

2. Connecting in Claude Code

In Claude Code, you can connect the ZeroLabs server using the command-line interface:

claude mcp add zerolabs https://labs.zeroshot.studio/api/mcp/sse

Alternatively, add it directly to your global Claude configuration file (~/.claude.json) under the mcpServers object using the same remote SSE URL, as documented in the Anthropic MCP Guide.

3. Seeing ZeroGuide in Action: The Turn-by-Turn Experience

Once connected, ask your agent in Cursor Composer or Claude Code using the shareable activation prompt:

Install the public ZeroLabs MCP from https://labs.zeroshot.studio/connect-mcp, then activate ZeroGuide on this guide: walk me through it step by step. Explain why each phase matters. Ask before each phase. Stop when I say stop.

Here is the authentic turn-by-turn coaching workflow captured live inside Cursor:

Step 1: ZeroGuide Discovery and Catalog Lookup

The developer asks Cursor Composer to inspect available guides on ZeroLabs. The agent queries the zeroguide MCP tool, returning the 4 active interactive coaching blueprints alongside their zone mappings and phase counts.

Step 2: Session Activation and Phase 1 Architecture

The coaching session begins for the target blueprint. ZeroGuide immediately serves Phase 1 (Zero-State Scaffolding and Directory Architecture), explains why directory taxonomy matters before code generation, and presents the approved workspace file tree.

Step 3: Paced Scaffolding and Verification Gate

When the developer instructs the agent to proceed ("Scaffold it"), the agent creates the 13 baseline workspace files, runs ./scripts/verify.sh to confirm zero test errors, and halts immediately with an explicit prompt before touching Phase 2.

Step 4: Phase 2 Delivery - The Core Workspace Contract (AGENTS.md)

Upon entering Phase 2, ZeroGuide writes the AGENTS.md operational contract across 7 mandatory sections, establishing the Immutable Test Rule to eliminate assertion erasure and setting up 2-failure circuit breakers.

Step 5: Phase 3 Extension Taxonomy (Hooks, Skills, MCP, Subagents)

In Phase 3, ZeroGuide explains the extension layer, displaying an architectural diagram and comparison matrix that contrasts execution triggers with token consumption across all four extension types.

Step 6: Phase 3 Artifact Wiring and Verification Hook

The agent wires the pre-commit hook (scripts/hooks/pre-commit), starter verification skill, and extensions reference doc into the repository, giving the developer explicit instructions to link the git hook.

Step 7: Deterministic Paced Halt and Resume Token

When pausing or concluding the session, ZeroGuide halts cleanly at Phase 3 of 8, summarizes completed milestones versus remaining phases, and injects a deterministic resume token (ZeroGuide resume: how-to-set-up-your-first-agent-coding-project phase 3/8) so future agent sessions can resume without re-reading the entire guide.

What Trade-Offs Did We Face During Implementation?

Building an interactive coaching protocol on top of MCP revealed three critical trade-offs that our team struggled with during testing and production rollout.

First, stateless RPC vs stateful coaching trade-off. The Model Context Protocol is inherently stateless between tool invocations. Servers do not hold long-lived conversational memory for specific clients unless tied to authenticated session cookies or client IDs. When we tested server-side session cookies, we discovered that client reconnects frequently broke active sessions. Rather than forcing developers to pass authentication tokens or managing server-side websocket sessions, we implemented client-side state tokens (resume_token). The server remains completely stateless, horizontally scalable, and edge-deployable, while the client prompt carries the resume context.

Second, token budget enforcement vs context completeness. In our early prototypes, when we dumped the entire article text alongside the phase map, the system failed because the LLM would self-regulate poorly. The model consistently tried to be helpful by summarizing all 6 phases at once, which broke the pacing workflow. We had to fix this bug by enforcing hard truncation at the API boundary: when a specific phase is requested, the endpoint returns only that phase data, strictly preventing context leakage. In our testing, this reduced active token consumption per interaction by 68%.

Third, tool naming backward compatibility. During internal testing, we evaluated two naming conventions: zeroguide and zeropath. When early testers reported tool lookup errors after naming updates, we realized that breaking client configs was unacceptable. Rather than maintaining split discovery endpoints, we registered both identifiers in the server router. Calls to zeroguide and zeropath execute the identical verified session engine, ensuring that early testers and new MCP client discovery manifests remain 100% compatible.

FAQ

What is ZeroGuide?
ZeroGuide is an interactive engineering coach exposed via the ZeroLabs public Remote MCP server. It breaks comprehensive architectural blueprints into turn-by-turn phases executed inside AI coding environments.

How is ZeroGuide different from standard documentation?
Standard documentation dumps thousands of words at once, causing agents to skip steps or hallucinate code. ZeroGuide delivers one milestone at a time, explains the engineering rationale, and verifies completion before moving forward.

Does ZeroGuide require an API key or paid subscription?
No. The ZeroLabs public MCP server is free to access and open to all developers. You can connect Cursor, Claude Code, or Windsurf directly to the remote SSE endpoint without signing up for an account.

Which blueprints are currently supported in ZeroGuide?
ZeroGuide currently supports all major ZeroLabs engineering blueprints, including our spec-first coding agent blueprint, self-hosting headless browser agent pools on Ubuntu VPS, and deterministic testing harness architectures.

---

Read the full architecture breakdown and canonical post on ZeroLabs. To connect the free public MCP server to your IDE, visit the ZeroLabs Connect Hub.