Skip to content

graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs

Python
12.9 KB
Raw Blame

Use Codegraff as an MCP tool and app

Automatic HTTP setup

The CLI installer runs graff mcp install. If graff came with the desktop app, Harness, run graff mcp install yourself once. Setup requires Python 3 (Python 3.11+ to validate Codex TOML), and macOS launchd or Linux user systemd.

Setup starts a shared service at http://127.0.0.1:7720/mcp, creates a private bearer token, and adds HTTP entries for detected Claude Code, Codex, Cursor, Gemini CLI, Windsurf and VS Code installations. Installer-owned entries refresh on later installs while unrelated entries and user-modified Codegraff entries are preserved. Malformed or JSON-with-comments files are left unchanged with a diagnostic. Restart clients to load their new entry. Clients that require stdio can use the manual configuration below.

The default workspace is your home directory; tasks remain approval-gated. To choose a fixed project and optional port, run:

graff mcp install --directory /absolute/path/to/project --port 7720

Subsequent installs retain that directory and port. Changing the port refreshes installer-owned entries; user-modified entries remain yours to update. Service installation restarts the managed listener, so finish active tasks first. Run graff mcp install again to configure clients installed later.

Set GRAFF_NO_MCP=1 when running the CLI installer to skip automatic setup. This does not stop a previously installed service. Stop/disable it using:

  • macOS: launchctl bootout gui/$(id -u)/dev.codegraff.mcp, then remove ~/Library/LaunchAgents/dev.codegraff.mcp.plist to prevent login startup.
  • Linux: systemctl --user disable --now codegraff-mcp.service.

Remove the codegraff entry from client configs if it is no longer wanted.

Run the HTTP listener yourself

export GRAFF_MCP_TOKEN="$(python3 -c 'import secrets; print(secrets.token_hex(32))')"
graff mcp serve --http --port 7720

Clients need that token in their Authorization: Bearer … header. The managed service keeps its token in ~/.graff/mcp/token and writes the matching headers into private client config files. The listener binds only to 127.0.0.1, checks the Host and Origin headers, and exposes only /mcp. There is no public bind or browser CORS access. The embedded UI is delivered through the MCP host.

POST accepts JSON-RPC and returns JSON, or HTTP 202 for accepted notifications. A 2026-07-28 request is stateless: no session, and its MCP-Protocol-Version, Mcp-Method and Mcp-Name headers must match the body (HTTP 400 with -32020 otherwise; an unknown version gets HTTP 400 with -32022). For the older revisions, initialization returns Mcp-Session-Id; later calls must send it. DELETE closes a session, and GET returns 405 (no SSE stream). The service retains up to 64 client handshakes, replacing the oldest on overflow; an evicted client gets 404 and must initialize again. Each client negotiates Apps support separately. Tasks across clients run serially and share the listener; each task still gets a fresh bounded child. HTTP saves duplicate listener startup, not model tokens or the per-task model startup. Existing task limits still apply.

graff mcp serve exposes Codegraff's task runner to local MCP clients. The client launches it over stdio, discovers run_task, and supplies a brief. Each call runs a fresh Codegraff child in the server's launch directory and returns its answer. Existing graff mcp add, list, and login commands still configure the MCP tools Codegraff consumes.

Manual stdio configuration

Use an absolute path to the built or installed graff executable in your client's MCP server configuration. For clients using mcpServers JSON:

{
  "mcpServers": {
    "codegraff": {
      "command": "/absolute/path/to/graff",
      "args": ["mcp", "serve"]
    }
  }
}

Set the server's working directory to the project using your client's cwd setting, or launch the client from that project. Calls cannot override cwd, credentials, permission mode, or arbitrary CLI flags.

Run graff login first for actual tasks. Initialization and tool discovery work without credentials. Tasks inherit the launch environment and existing Codegraff configuration. To pin a model, append --model NAME to the server arguments; otherwise Codegraff uses its normal configured model selection.

By default tasks use --safe: permission-gated operations are denied when there is no interactive approval channel. For unattended coding in a trusted workspace, explicitly append --yolo to the server launch arguments. This authorizes the ordinary Codegraff tools, including file edits, commands, and configured MCP tools. It is not an OS sandbox; the client must approve and scope task calls appropriately. Review resulting edits before integrating.

Call the tool

{
  "name": "run_task",
  "arguments": {
    "prompt": "Explain how the configuration parser handles missing values. Cite the relevant files. Do not change files.",
    "context": "We are on release/v0.0.292; the parser was rewritten last week and the old walker is gone.",
    "timeout_seconds": 120,
    "max_model_calls": 8
  }
}

A useful brief includes the concrete task, permitted scope, and acceptance criteria; background the child cannot re-derive goes in context. There is no inherited client conversation: the child sees only what you pass. Prefer small explanations, focused reviews, test runs, and narrowly scoped fixes.

  • prompt: required, nonblank, at most 32 KiB of UTF-8 text.
  • context: optional background for the child — relevant history, decisions, file paths or constraints. Nonblank, at most 32 KiB of UTF-8 text. It is appended to the child's system prompt. At or below 8 KiB it is passed through verbatim; above that the server summarizes it first, because a fresh child cannot consume the gateway's opaque compaction state and a large handover would otherwise crowd out the task itself. Summarizing runs under the same credentials, so it bills to the same account, and it never touches the workspace: the summarizer runs --safe with no tool budget.
  • timeout_seconds: 1–300, default 120. The summarizer's own deadline is capped separately at 60s and does not consume this budget.
  • max_model_calls: 1–32, default 8, shared across the child invocation. The summarizer runs on its own single-call budget.
  • Root tool calls are capped at 64 per turn.

When Graff calls this tool over HTTP, its transport waits for the validated child budget, any required context summarization, and 15 seconds for cleanup and the final partial-output reply. Discovery and unrelated tools retain their normal deadlines. Other MCP hosts control their own transport timeouts: allow at least the task timeout plus 15 seconds, or plus 75 seconds when context exceeds 8 KiB. A shorter host timeout can discard the reply; it does not prove the child stopped, and this tool has no continuation handle.

context carries text only. It cannot set cwd, credentials, model, permission mode, or any CLI flag — those still come from the server launch.

The MCP result contains text, isError, and schema-described structuredContent with text, status, output_truncated, timeout_seconds, max_model_calls, context_chars, context_summarized, context_used_chars, usage_reported, usage_unavailable_reason, and preprocess. The last three context fields report the context the caller sent, whether it was summarized, and how much text the child actually received. If summarization fails the task is not run and the error says so, rather than silently dropping the context.

The same object is also mirrored under _meta["codegraff/runTask"] on the tool result, so a client that renders the raw result can show supplied-context size and summarization state without parsing prose. Those facts also cross into ACP: a completed tool_call_update carries _meta["codegraff/runTask"] (alongside _meta["graff/view"] when the result opened a view), so an ACP client such as Harness renders them the same way. Only the fields above travel — never the task's text and never the caller's context.

Per-task usage and charge for the child's own execution are not reported. usage_reported is always false, with usage_unavailable_reason naming the cause: the task child runs in print mode, which exposes no settled gateway charge, and a charge is never derived from list rates (src/pricing_settled.zig). This is a known limit, not an unimplemented field — account-wide gateway usage remains authoritative for what a task cost.

Preprocessing is reported, separately. When context had to be summarized, preprocess carries cost_usd, usage_complete, input_tokens, output_tokens and unavailable_reason. The summarizer runs as a --json child — print mode reports no settled charge — with its one request line on a file-backed stdin, so the engine's exact-charge ingestion supplies the number and no pipe has to be fed concurrently. An incomplete report (usage_complete: false, or any unpriced_calls / missing_usage_calls) yields cost_usd: null with a reason; a list-rate estimate is never presented as a settlement. Preprocessing is reported in its own object and never folded into the child total, so it cannot be double-counted. When no summarization was needed, unavailable_reason says so and the tokens are zero.

Status is completed, failed, timed_out, or cancelled. Process failures and deadlines return an error with partial output; changes made before failure are not rolled back. Successful exit reports the harness answer, not independent verification of its claims. Answers are capped at 64 KiB and failure diagnostics at 16 KiB, with explicit truncation markers.

Embedded task result

Hosts advertising io.modelcontextprotocol/ui with MIME type text/html;profile=mcp-app receive UI metadata on run_task. The host reads ui://codegraff/task-result and renders the bundled task panel in its sandbox. It shows completion status, configured limits, truncation, the task brief, and searchable output with a line-wrap control. Theme changes follow the host. The embedded conversation uses the desktop palette from src/ui_theme.css, compiled into the MCP resource, with the same task chrome, user bubble and response layout.

No extra server, package install, or network access is needed for the view. The panel is a result inspector: it does not run or retry tasks, stream progress, or change permissions. Submit follow-up tasks through the host conversation. Clients without the extension receive the ordinary tool with the same text and structured result. UI support depends on the host; MCP tool support alone does not imply embedded-app support.

The HTML requests no external domains or device permissions. Model output is rendered as literal text. Resources list/read expose only the bundled template, never workspace files or saved task data.

See the MCP Apps specification.

Lifecycle and limits

The server implements server/discover, ping, tools/list, tools/call, resources/list, resources/read, and an empty resources/templates/list using newline-delimited JSON-RPC on stdin/stdout.

  • 2026-07-28 (stateless): each request carries its version and client capabilities in _meta; no initialize. Results carry resultType, and discovery, list and read results add ttlMs and cacheScope: "public". An unknown version gets -32022 with supported and requested.
  • 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05: the initialize handshake, negotiating 2025-11-25 for an unknown revision. server/discover without _meta is method-not-found, so dual-era clients fall back.

See the MCP specification.

Calls run serially. This initial adapter has no progress stream, live cancellation, session continuation, or background task handle. Keep the client's tool timeout longer than timeout_seconds to receive the terminal result. If a client disconnects during a call, the child can continue until its deadline; the runner terminates its process tree on deadline.

The child inherits a recursion marker. A nested graff mcp serve launch is refused, preventing a configured Codegraff server from recursively delegating to itself. Each call starts fresh; unrelated environment and workspace configuration still follow the ordinary harness behavior.

Run the offline integration check with python3 scripts/test-mcp-server.py after zig build. It uses the local scripted model on port 1234.

For the embedded view regression, run node scripts/test-mcp-task-app.cjs with @playwright/test resolvable and Chrome installed. It uses a local opaque iframe and checks the handshake, presentation controls, themes, mobile layout, text-only rendering, cancellation notification and teardown.

HTTP and setup checks: python3 scripts/test-mcp-http.py and python3 scripts/test-install-mcp.py.