Skip to content

docs/abc: Document Agentic Batch Changes over MCP - #2152

Draft
valerybugakov wants to merge 3 commits into
mainfrom
vb/abc-mcp-docs
Draft

valerybugakov wants to merge 3 commits into
mainfrom
vb/abc-mcp-docs

Conversation

@valerybugakov

@valerybugakov valerybugakov commented Nov 12, 2026 •

Copy link
Copy Markdown
Member

Adds a page for using Agentic Batch Changes from an MCP client through the dedicated /.api/mcp/abc endpoint: access tokens and scopes, connecting Claude Code, Codex and Cursor, the tools, waiting for updates, errors, limits and security.

⚠️ Draft for the broader release. Don't merge until the tools below ship and we've dogfooded them internally; we're not announcing this externally before then.

Changes

  • agentic-batch-changes/mcp.mdx: new page.
  • api/mcp/index.mdx: add /.api/mcp/abc to the Server Endpoints table.
  • src/data/navigation.ts: add MCP under Agentic Batch Changes.

Merge timing

Publish after these sourcegraph/sourcegraph PRs merge and internal dogfooding is done:

  • Endpoint, token scopes and minting rule: sourcegraph/sourcegraph#18852
  • Approvals and standing approvals: sourcegraph/sourcegraph#18853, sourcegraph/sourcegraph#18854
  • Token page scopes: sourcegraph/sourcegraph#18855
  • Execution logs reader: sourcegraph/sourcegraph#18875

The read and control tools are already on main (sourcegraph/sourcegraph#18773 to sourcegraph/sourcegraph#18786). The tools stay behind the abc-mcp feature flag until rollout.

@vercel

vercel Bot commented Nov 12, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
sourcegraph-docs Ready Ready Preview Nov 18, 2026 8:08am UTC

Request Review

@github-actions

Copy link
Copy Markdown
Contributor

@github-actions

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor
Page Before After Diff
/agentic-batch-changes/mcp 🆕 — preview +439
/api/mcp prod preview −5 +6

@github-actions

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

⚠️ Spell check found 3 issue(s) in this PR

Only findings on lines added by this PR, and in its title and description, are shown.

docs/agentic-batch-changes/mcp.mdx

Pull request description

  • line 3, column 84
    • dogfooded → doggoned
  • line 13, column 68
    • dogfooding → doggoning

Please correct the spelling, or add words which are correct to cspell-allow-list.txt.

Comment on this PR with /spell <list of words>, and a bot will push a commit to your branch adding your comment's list of words to cspell-allow-list.txt for you.

To accept all of the words above as correct: /spell nonblank dogfooded dogfooding


- `message` - The change to make, with context, constraints, and what must not change (required, up to 32,768 characters)
- `repositories` - Full repository names such as `github.com/org/repo` (optional, up to 1,000). Omit to let the agent find repositories.
- `request_key` - A nonblank key you generate, such as a UUID (required, up to 200 characters). Reuse it with identical input on every retry; a retry returns the first agent instead of starting a second one.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nonblank is not in the dictionary.

Did you mean nolan?

Suggested change
- `request_key` - A nonblank key you generate, such as a UUID (required, up to 200 characters). Reuse it with identical input on every retry; a retry returns the first agent instead of starting a second one.
- `request_key` - A nolan key you generate, such as a UUID (required, up to 200 characters). Reuse it with identical input on every retry; a retry returns the first agent instead of starting a second one.

Please correct the spelling, or add words which are correct to cspell-allow-list.txt.

Comment on this PR with /spell nonblank, and a bot will push a commit to your branch adding it to cspell-allow-list.txt for you.

@constantin-cyber constantin-cyber left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Four correctness fixes to address before publishing, plus two smaller clarifications. Checked the documentation against the Sourcegraph implementation. The client configuration examples checked out.


- Agentic Batch Changes is available to you. The read tools need `Batch Changes: Read` and `Batch Changes: Agent Read`; tools that start or change an agent also need `Batch Changes: Write` and `Batch Changes: Agent Write`. See [Access](/agentic-batch-changes/configuration#access).
- MCP is enabled and you have the `MCP#ACCESS` permission. See [Availability and access control](/api/mcp#availability-and-access-control).
- The `abc-mcp` feature flag is on for you. A site admin creates it under **Administration > Configuration > Feature flags** and enables it for users or organizations. While it is off, the endpoint lists no tools and every call returns `FEATURE_DISABLED`.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] Distinguish Cloud and self-hosted flag enablement

These instructions apply to self-hosted instances, but Sourcegraph Cloud normally restricts flag creation and overrides to Sourcegraph operators, including when the caller is a customer administrator. Please document the managed enablement path for Cloud and qualify the note below about users enabling their own overrides. Otherwise Cloud readers hit an authorization failure at the first prerequisite.

Both creation and override mutations enforce the Cloud operator check, unless SRC_CLOUD_ALLOW_FEATURE_FLAG_MANAGEMENT_MUTATIONS is explicitly enabled.


- `agent_id` - (required)
- `decision_id` - From `read_batch_change` (required)
- `answers` - One entry per question, 1 to 100 (required). Each has `question_id`, and either `option_id` or `text`. Omit both to skip that question.

@constantin-cyber constantin-cyber Nov 16, 2026 •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] Document freeform choice answers correctly

option_id and text are not mutually exclusive. When a client supplies an option ID whose option has freeform: true, it must also supply nonempty text. Sending that option ID alone produces INVALID_ANSWER.

A text-only answer with no option_id is also valid, including for an options question. I confirmed this in the live local MCP flow. Please distinguish fixed-choice answers, a selected freeform option with text, text-only answers, and explicit skips. For the selected freeform-option form:

{"question_id":"q0","option_id":"other","text":"Only frontend repositories"}

See answer validation and the MCP freeform-answer test.

#### `start_batch_change`

<details>
<summary>Start an attended agent. It plans and makes the change; publishing waits for your approval.</summary>

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] Qualify the promise of a fresh publication approval

A new attended agent can publish drafts without another approval prompt when the owner already has covering standing authority from all_attended_agents. For example, standing draft authority granted for repository A on an earlier agent also covers a new attended agent publishing a draft there.

Suggested wording: "Publication requires your approval unless an existing standing approval covers the repositories and publication mode." Please link to inspecting and revoking standing approvals, and make the same qualification in Limitations.

Coverage includes standing grants, and the worker skips the approval request when publication is covered.


- `message` - The change to make, with everything the agent needs without a person present (required, up to 32,768 characters)
- `repositories` - Repository names (optional, up to 1,000)
- `query` - A Sourcegraph search whose matching repositories join the scope (optional, up to 32,768 characters)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] State the combined unattended scope requirement

Both repositories and query are individually marked optional, but omitting both always fails with EMPTY_SCOPE. Unlike attended start, an unattended agent cannot discover its initial scope automatically.

Please add: "Provide at least one of repositories or query; their union must resolve to at least one accessible repository."

Unattended start always resolves the supplied scope, and empty resolution is rejected.

- `{"decision":"allow"}` keeps the requested mode and the `this_agent` scope.
- `{"decision":"allow","publication":{"mode":"draft","scope":"this_agent"}}` sets both. `mode` must match the request, except that `ready` can be lowered to `draft`.
- With `"scope":"all_attended_agents"`, allowing also saves standing draft authority over the reviewed repositories for all your attended agents.
- `{"decision":"request_changes","note":"What to change"}` declines and gives the agent feedback.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestion: document approval retry identity

Please add that a retry must use identical fields, preserving omitted fields. Adding explicit defaults on a retry can return ALREADY_DECIDED, even if the caller considers the responses equivalent. For example, retrying an allow response that omitted publication by adding its explicit default mode and scope is not the same request.

This is part of the approval tool's documented contract. The page already explains retry identity for starts and question answers; the approval section needs the corresponding caveat.

#### `read_batch_change_workspace_diff`

<details>
<summary>Read a workspace's patches, page by page.</summary>

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestion: explain when a diff comes from a previous run

Please document source: "previous_run" and changeset_spec_id in the response. A workspace without current output can return an earlier run's patch, and one workspace can produce multiple branch patches. Readers reviewing the current change need to distinguish these results.

Both fields and the fallback behavior are explicit in the response schema and tool description.

This branch was successfully deployed

1 active deployment
Preview — 8006a566 Deployed Nov 18, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants