What is MCP?

MCP (Model Context Protocol) is an open standard created by Anthropic that defines how AI agents communicate with external tools. It works like a USB-C port for AI — a single protocol that lets any compatible agent (Claude Code, Cursor, VS Code Copilot, etc.) discover and call tools exposed by any compatible server.

How it works

An AI agent starts your MCP server as a subprocess (e.g., gs mcp)
They communicate over stdio using JSON-RPC 2.0 (one JSON message per line)
The agent discovers available tools via a tools/list call
The agent calls tools by name with structured arguments
The server returns structured JSON results

There is no HTTP, no daemon, no port. The server lives for the duration of the agent session and exits when stdin closes.

Core concepts

Concept	Description
Server	A process that exposes tools (`gs mcp`)
Tool	A function the agent can call (e.g., `gs_status`, `gs_create`)
Transport	How messages flow — gs uses stdio (stdin/stdout)
Capabilities	What the server supports — gs exposes tools only (not resources or prompts)

Why MCP for gs?

The problem

gs output is designed for human eyes — ANSI colors, Unicode box-drawing, column-based tree art. When an AI agent runs gs log, it gets a wall of escape codes that it has to parse heuristically. This is fragile, lossy, and wastes tokens.

What MCP solves

MCP gives AI agents a native machine interface to the same data. Instead of parsing:

│ ○ feat/auth-tests
│ │   def5678 add test helpers
│ ◉ feat/auth
│     abc1234 add auth middleware
main

An agent calls gs_status and gets:

{
  "trunk": "main",
  "current_branch": "feat/auth",
  "branches": [
    { "name": "feat/auth", "parent": "main", "children": ["feat/auth-tests"], "depth": 1 },
    { "name": "feat/auth-tests", "parent": "feat/auth", "children": [], "depth": 2 }
  ]
}

This separation means:

The CLI stays human-first — no --json flags polluting the interface
The MCP server is machine-first — structured data, no parsing, no ANSI
Same engine underneath — both use the same core stack operations

What AI agents can do with this

Inspect the full stack tree before making changes
Create stacked branches as part of a multi-PR workflow
Restack/rebase automatically after modifying a branch mid-stack
Navigate the stack to understand where they are working
Delete, move, fold, and rename branches programmatically
All without parsing terminal output or guessing at state

MCP Overview