Editor & MCP client setup

The same madtea binary serves an MCP endpoint over stdio (madtea serve). The consolidated MCP tools (one per resource noun, action-dispatched — issues, prs, repos, branches, releases, actions, …) are identical across every client; only the config file’s location and format differ.

Every client launches the server the same way — running the madtea binary with the single argument serve and talking to it over stdio. The blocks below differ only in how each client spells that out.

Note on command. The snippets use the bare name madtea, which works when the binary is on your PATH. If it isn’t, replace madtea with its absolute path (e.g. /home/you/go/bin/madtea). madtea mcp-config auto-fills the absolute path when it can resolve one.

Resources & prompts (optional convenience). Beyond the tools, the server also advertises a few read-only MCP resources (docs URIs under madtea://docs/… — getting started, the workflow, the madt_help topic index, and the design ADR) and a few MCP prompts (start-feature, finish-branch, file-issue) for common flows. Clients that support resources/list+resources/read or prompts/list+prompts/get (e.g. the prompt picker in some UIs) can browse and invoke them with no extra config. These docs resources are a convenience only — they restate facts the server instructions, tool schemas, and madt_help already carry, so safe, correct use never depends on a client supporting them.

Forge resources (credentialed, live data). When Forgejo/Gitea credentials are configured, the server also advertises a set of read-only resource templates (plus one fixed resource) exposing exactly ONE forge item at a time — never a list, search, or mutation surface; those stay on the madt_* tools. Unlike the docs resources above, these carry real forge data and are only advertised once credentials are set up; a credential-less server never lists them.

URI template	MIME	Reads
madtea://{owner}/{repo}/issues/{id}	text/markdown	One issue: title, state, metadata, full body, chronological comments — same data as madt_issues action="get".
madtea://{owner}/{repo}/prs/{id}	text/markdown	One pull request, comments included — more than madt_prs action="get" alone (comments need a separate action="comments" call there).
madtea://{owner}/{repo}/files/{+path}	varies (text/plain, text/markdown, application/json, or a sniffed binary MIME)	One repository file’s content or one directory’s listing, from the default branch only; large/binary reads are capped.
madtea://{owner}/{repo}/commits/{sha}	text/markdown	One commit’s SHA, author/committer, message, parent SHAs, and changed-file stats — no diff (use madt_commits action="diff" for that).
madtea://{owner}/{repo}/branches/{name}	text/markdown	One branch’s protection state and latest commit. A /-containing name must be percent-encoded by the client.
madtea://{owner}/{repo}/releases/{id}	text/markdown	One release’s tag, name, notes, and asset metadata (name/size/download link) — addressed by numeric id, not tag.
madtea://{owner}/{repo}/milestones/{id}	text/markdown	One milestone’s title, state, description, due date, and issue completion counts.
madtea://{owner}/{repo}/metadata	application/json	Repository facts: description, language, default branch, visibility/archived/fork/mirror flags, size, star/fork/watcher/open-issue counts, timestamps, topics, licenses.
madtea://{owner}/{repo}/wiki/{page}	text/markdown	One wiki page’s title, last-updated author/date, and rendered body (bounded).
madtea://{owner}/{repo}/backlog/rank	text/markdown	A bounded snapshot of the open-issue backlog ranked by dependency readiness and open blockers and unblocks count — the same computation as madt_issues action="rank", not a substitute for its full option set.
madtea://{owner}/{repo}/labels	application/json	Repo-scoped label taxonomy (id/name/color/description/exclusive/archived), capped at 500 labels / 256 KB.
madtea://{owner}/{repo}/actions/runs/{run_id}	application/json	Fixed ~1 KB metadata for one Actions workflow run — no jobs or logs (those stay madt_actions tool calls).
madtea://server/info (fixed resource, not a template)	application/json	Detected server platform and version — same two fields as madt_server_info, a closed allowlist with no credential/identity material.

Annotations (client ranking hints). Every resource and template — the docs resources above and every forge resource in this table — carries MCP annotations: audience: ["assistant"] (these are assistant-facing forge context, not end-user copy) plus a priority hint clients use to rank resources for context inclusion. Live forge state (issues, PRs, commits, branches, releases, milestones, metadata, wiki, labels, an Actions run, server/info, files) is 0.5; reference or computed material (the madtea://docs/… resources, madtea://reference/{noun}, and backlog/rank) is 0.2 — lower, so a client under context pressure keeps live forge state and sheds restatable reference material first. Clients that don’t consume annotations simply ignore them.

Any MCP client — print and paste

madtea mcp-config prints a ready-to-paste config block. When --client is omitted it auto-detects which supported agent is installed: exactly one found → target it automatically; multiple found → list them and require --client <name>; none found → error with guidance. The default JSON mcpServers shape is what Claude Code, Cursor, Windsurf, and Cline accept verbatim:

madtea mcp-config                              # Auto-detect agent; print JSON snippet
madtea mcp-config --client claude              # Explicit: Claude Code JSON snippet
madtea mcp-config --client codex               # TOML, [mcp_servers.madtea] shape
madtea mcp-config --client antigravity         # JSON, stdio shape for Antigravity

The default JSON block is:

{
  "mcpServers": {
    "madtea": {
      "type": "stdio",
      "command": "madtea",
      "args": ["serve"]
    }
  }
}

Paste it into the MCP-servers section of your client’s config file:

Claude Code

Two paths — pick one:

• MCP only (works on any plan, no clone): madtea install is the single setup command — it installs the binary, shell completions, and registers the server with Claude Code (running claude mcp add -s user madtea ..., which writes to ~/.claude.json). To re-register the MCP server without touching the binary or completions:

  madtea install --skip-binary --skip-completions   # runs: claude mcp add -s user madtea ...
  

• Plugin (Claude Code convenience): add the sixfold plugin marketplace, then install from it:

  /plugin marketplace add https://codeberg.org/sixfold_space/claude-plugins.git
  /plugin install madtea@sixfold-plugins
  

  The plugin layers the forge-workflow and dev-workflow skills and seven safety hooks on top of the same MCP tools. It’s optional — it adds only the skills and hooks (it does not register the MCP server or ship the binary); MCP-only users can skip it.

Either path is zero-config: you do not paste anything into CLAUDE.md or AGENTS.md. The server instructions, tool/action schemas, and madt_help(topic) carry every usage and safety rule on their own — see the agent onboarding matrix, which inventories all of them and confirms none lives in operator config.

Optional: reinforce in your own CLAUDE.md

This is not required. The MCP tools, server instructions, and madt_help already carry every rule below, so an agent with no CLAUDE.md (or one you’d rather not touch) is fully covered. This snippet only nudges — it’s worth adding only if you already keep a CLAUDE.md and want forge rules stated there too:

For Forgejo/Gitea, always use madtea (madt_finish, madt_clone, madt_push, …)
instead of raw git — madtea routes credentials so they never leak into argv,
shell history, or errors. Workflow: feature branch → madt_finish (PR + merge +
return to default). Run madt_help(topic) for anything else.

OpenAI Codex CLI

Codex uses TOML, not JSON. Let madtea run Codex’s own mcp add for you:

madtea install --mcp-client codex     # runs: codex mcp add madtea …

Requires the codex CLI on PATH. Writes to ~/.codex/config.toml. To paste manually instead, run madtea mcp-config --client codex to print the block:

[mcp_servers.madtea]
command = "madtea"
args = ["serve"]

No guardrail hooks on this client. The seven git-safety hooks are Claude Code PreToolUse hooks (shipped with the Claude Code plugin), so Codex doesn’t get them. You still have the full anti-leak protection at the MCP level — madt_clone / madt_finish and friends route the token through GIT_ASKPASS, never into argv, history, or errors. What’s missing is the hook-level backstop that intercepts raw git push/git remote -v typed straight into Codex’s shell. If your agent shells out to raw git against a repo whose remote URL embeds a token, nothing here stops it. See credential safety.

Google Gemini CLI (retired — use Antigravity)

The Gemini CLI was shut down on 2026-06-18 and now returns HTTP 410 for everyone outside a Gemini Code Assist Standard/Enterprise license (or a paid API key); its successor is the Antigravity CLI (agy). madtea wiring the dead CLI’s front door would fail for most users, so the gemini client is now a one-cycle deprecation stub: hidden from auto-detection, removed from help, and refusing on both surfaces before it removes entirely next release.

• madtea install --mcp-client gemini refuses and points at madtea install --mcp-client antigravity.
• madtea mcp-config --client gemini also refuses (nonzero) but still prints the manual snippet, so an enterprise Code Assist license holder can paste it into ~/.gemini/settings.json:

{
  "mcpServers": {
    "madtea": {
      "command": "madtea",
      "args": ["serve"],
      "trust": false
    }
  }
}

Antigravity

Antigravity CLI (agy) is the successor to the Gemini CLI. It has no mcp add command (it auto-imports legacy config on first run), so madtea install --mcp-client antigravity direct-writes ~/.gemini/antigravity-cli/mcp_config.json (merging into any existing config):

madtea install --mcp-client antigravity   # writes ~/.gemini/antigravity-cli/mcp_config.json

To paste manually instead, run madtea mcp-config --client antigravity to print the block:

{
  "mcpServers": {
    "madtea": {
      "type": "stdio",
      "command": "madtea",
      "args": ["serve"]
    }
  }
}

Local stdio, so the serverUrl rename doesn’t apply. The Gemini-CLI → Antigravity migration renamed the MCP url key to serverUrl, but that affects remote (URL-based) servers only. madtea runs locally over stdio (command/args), so its entry is unchanged by the rename — the block above is the current shape.

No guardrail hooks on this client. The seven git-safety hooks are Claude Code PreToolUse hooks (shipped with the Claude Code plugin). The full anti-leak protection still applies at the MCP level — madt_clone / madt_finish and friends route the token through GIT_ASKPASS, never into argv, history, or errors. See credential safety.

False “not configured” reading. Antigravity’s own MCP-server status list may show madtea as not installed even right after wiring. That’s a discovery quirk, not a broken install: Antigravity exposes madtea’s tools through local custom-tool files instead of registering it through the standard MCP-server path its status check looks at, so the check misses it while the tools themselves keep working. Confirm directly instead — invoke any madt_* tool (e.g. madt_status) or open ~/.gemini/antigravity-cli/mcp_config.json and check for the madtea entry.

Zed

Zed does not use the mcpServers shape — it keys MCP servers under context_servers in its settings.json. madtea mcp-config doesn’t emit this form, so paste it by hand:

{
  "context_servers": {
    "madtea": {
      "command": "madtea",
      "args": ["serve"],
      "env": {}
    }
  }
}

Open settings.json with Cmd+, (macOS) / Ctrl+, (Linux/Windows), or run zed: open settings from the command palette — Zed reopens the running server automatically when you save.