gitstalk docs mcp

MCP tools and scopes live

The Gitstalk MCP server gives your agent short, task-shaped tools: find work, open a bean, wait for its verdict, read code without a checkout. You choose what the agent may do when you approve it, and no tool can merge a change or answer a decision card.

Connect

With the plugin this is one line and a browser tab. Without it, any client that speaks remote (HTTP) MCP can connect to the same address:

claude mcp add --transport http gitstalk https://mcp.gitstalk.io/mcp && claude mcp login gitstalk

1. The client finds the server

   It asks the server how to sign in (OAuth 2.1 discovery) and registers itself. The server supports dynamic client registration and client ID metadata documents, with PKCE (S256).

2. You approve once

   Your browser opens the Gitstalk consent screen below. Sign in with a passkey or an email code, pick the scopes, press Allow.

3. The agent works as you

   Access tokens last 15 minutes and refresh on their own; a session that goes unused for 30 days ends. You can disconnect it any time in Settings, which revokes its tokens.

A personal token (bsu_…, made in Settings → Tokens) also works as the bearer for a script that cannot open a browser. See accounts, tokens and keys.

The consent screen

The screen shows who published the client, where the access goes and which account the agent acts as. read cannot be unticked. secrets stays unticked even when the agent asks for it: you opt in yourself. create is ticked only when the agent asks for it.

Scopes and roles

A scope says what the agent may ever do. Your role on each repository says what you may do there. Both are checked on every call, so an agent never goes beyond you.

An agent is offered only the tools its scopes allow. Without write it sees no tool that opens beans or starts runs; without secrets it cannot touch secrets; without create it cannot create repositories. If your agent is missing a tool, reconnect it and tick the scope. See troubleshooting.

The tools

Tools take repo: "owner/name" and answer compact JSON, with a preview_url that opens the same view in the web app where a page helps. Reads are marked read-only; cancelling a run and changing a secret are marked destructive.

Decision-card tools are planned: today a card is answered by a person, not an agent.

Who sees what

The server registers a tool only when the caller's token could ever use it, so an agent never picks a tool that must fail. The exact sets are asserted by a test.

Run tokens are for benchmark races only: an operator mints them for one race. As a developer using Gitstalk you only ever meet the session rows.

Common tasks

Wait for a verdict

After a push, an agent with no other work calls bean_wait. It returns when the bean's check ends, or when the bean reaches the stalk with until: "stalk". It waits up to 300 seconds by default and at most 1,800. Never sleep-poll.

bean_wait { "repo": "acme/api", "bean": "add-truncate", "until": "verdict", "timeout_s": 600 }

The answer is the same as bean_status plus waited_s and timed_out: the phase, the failing tests, and the landed beans a red collided with. Plain git does the same: git push -o bean=add-truncate origin HEAD:refs/wait/any.

Edit with no checkout: bean_commit

For small edits (a doc, a revert, a conflict fix) an agent can send the changed files and nothing else. Gitstalk builds the commit and submits it as a push, so its pre-land check starts as usual. An agent with a checkout keeps using git.

bean_commit {
  "repo": "acme/api",
  "bean": "docs-truncate",
  "expected_head": null,
  "message": "Document truncate",
  "idempotency_key": "docs-truncate-1",
  "changes": [
    { "path": "docs/truncate.md", "content": "# truncate\n..." },
    { "path": "docs/old-truncate.md", "delete": true }
  ]
}

• Limits. At most 64 paths, 128 KiB per file and 192 KiB in all. Paths are relative, inside the repository, and never touch .git.
• expected_head is the branch head you read. Use null to create the branch from the sprout. If the branch moved, nothing is written and you get a conflict answer to retry from: { "kind": "conflict", "current_head": "…" }.
• idempotency_key is required. Make a new one for each attempt and reuse it only for an exact retry, which replays the first result.
• Protected paths need a person, as with a git push by an agent: the check fails and says so (see Checks). A bean that already landed takes no new commit; start a new bean.

Approve a held bean: bean_approve

When a repository's approval rules hold a bean for a person, bean_status answers held: true, an approve_url (the bean's page, with its Held panel) and a next step. An agent tells its person and waits; it approves only when the person says so.

bean_approve {
  "repo": "acme/api",
  "bean": "token-refresh",
  "revision": "4e1c9a2f0b7d3e5a8c1f6b2d9e0a7c4b3f5d8e1a",
  "note": "Ada read the expiry change and said approve it.",
  "idempotency_key": "approve-token-refresh-1"
}

• Who. The session needs write, and its person the maintain role or ownership. It must act for a person; an automation never approves.
• revision defaults to the bean's pushed head. A revision that is no longer the head is refused: a new push needs a new approval.
• Its own bean. When the bean's latest push was made for the same person and Gitstalk cannot show another agent session made it (this agent client, the person's SSH key or personal token), the call is refused. confirm_owner_intent: true lets it through, and an agent sets it only after its person confirmed.
• The answer is the receipt (who, when, client, revision, note) and the next step: the bean's check runs again, and bean_wait wakes at its verdict. The approval goes into the repository's access log as "via MCP (<client>)". Reuse idempotency_key only for an exact retry.

Read code: repo_read

repo_read { "repo": "acme/api", "path": "src/truncate.ts", "start": 1, "end": 80 }
repo_read { "repo": "acme/api", "glob": "src/**/*.ts" }
repo_read { "repo": "acme/api", "grep": "/retry\\w+/", "glob": "src/**/*.ts" }

• A file path (or up to 20 paths) returns contents, cut to about 25k tokens with next_start saying where to read on.
• A directory path or a glob returns a tree listing.
• grep takes a literal or a /regex/ and returns matches with two lines of context, about 8k tokens a page. Continue with cursor: next_cursor.
• ref is sprout (default), stalk, a bean branch or a commit.

Why a line is the way it is

Before editing, ask which bean last changed the lines and what it was for:

why_lines { "repo": "acme/api", "path": "src/tax.ts", "start": 10, "end": 40, "ref": "sprout" }

See Why this line: blame by bean for what comes back.

Take a task from the backlog

A repository's backlog is a Markdown task list in the repository, read from the sprout: .gitstalk/backlog.md, else BACKLOG.md. task_list shows each task as open, claimed, in progress or done.

- [ ] add-total: Add a total helper
  Sum the line items; keep it pure.
- [x] T-2: Rename the cart module

task_claim holds a task for two hours so no other agent takes it. Claim again, or bean_open with task, to keep it. A bean you pushed for the task holds it until it lands. task_claim with release: true gives it back. Changing the backlog is a bean like any other change.

Names that changed on 14 October 2026

If an older note or a still-deployed server shows different names, this is the mapping: