Version: Insiders
Feature:
Recommendation: First-class PR review state and concurrency-safe review workflows for GitHub MCP Server
Feedback:
Context
I use the GitHub MCP Server in agentic workflows where GitHub is not only source control but also the accountability and provenance layer for collaboration between multiple AI agents and humans.
The server is already highly useful. This feedback focuses on capability gaps that force agents to reconstruct authoritative pull-request state from many separate objects and operations, then act on it with no guarantee that the state is still current.
Environment: MCP host/client: <name + version> · Server: <remote/local, version/build> · Insiders feature under evaluation: <feature> · OS/IDE: <if applicable>
Scope note: Some failures below may originate in the MCP host's approval layer rather than the server. I have not isolated which. Part of this request is for error semantics that make that distinction possible. I have not yet reproduced these against an Insiders build.
Core problem: observe → reason → act, without state validation
Agentic workflows follow a recurring pattern:
- Inspect state
- Reason about it
- Act on it
Today an agent has no reliable guarantee that the state observed at step 1 is still valid at step 3, and no single answer to:
"What is the authoritative current state of this pull request?"
The capabilities below all address that gap.
1. Current authoritative PR review state as a single object
An agent currently assembles review state by stitching together multiple independent calls. That is fragile and makes it hard to distinguish findings that are current from those that are stale, outdated, superseded, or dismissed.
This matters most when:
- Multiple AI agents review the same PR
- Humans and agents alternate changes
- Reviews are made against different commits
- Threads become outdated after code changes
- Comments, reviews, checks, and metadata change independently
- Approvals are dismissed
- Mergeability or required-check status changes
Requested: one operation that returns the complete current review state, including:
- PR metadata, head SHA, base SHA, and mergeability
- Current merge readiness and blocking conditions
- Branch-protection requirements relevant to merging
- Changed files and current diff
- Review decisions (approved / changes requested), including dismissed reviews
- All review threads, with resolved/unresolved state, reviewer identity, body, file/line association, and whether each is outdated
- Issue comments and PR comments
- Linked issues and linked PRs
- CI / check status
- Latest review timestamps
- The relationship between each review/comment and the commit or review state it was made against
The response should also include a stable review-state generation/snapshot identifier (ETag-style or equivalent) so an agent can later establish that the state it inspected is still current.
2. Thread-aware review operations
First-class operations to:
- Reply to a specific review thread
- Resolve or reopen a specific thread
- Retrieve the current state of an exact thread
- Enumerate unresolved threads
These should be explicitly thread-aware rather than requiring agents to infer thread identity from individual comments. They should also verify (or supply the information needed to verify) that the thread is still current before any mutation.
3. Optimistic concurrency for writes
Write operations should accept an expected-state token, for example:
expected_head_sha = <SHA>
expected_review_state = <generation/token>
If either has changed, the mutation should be refused with a machine-readable conflict rather than silently applied.
Head SHA alone is insufficient: a thread can be resolved, reopened, commented on, or dismissed while the head remains unchanged.
Conflicts should return enough information for a client to determine what changed and whether an automatic retry is safe, for example:
STALE_STATE_CONFLICT
expected_review_state = A
actual_review_state = B
rather than a bare conflict with no state information.
Related requests:
- Post-write state token: Every mutation should return the resulting review-state token so an agent can verify its own write without re-reading the entire PR state.
- Idempotency keys for create operations: Comments, reviews, and other create operations should accept idempotency keys. A retry after a timeout or ambiguous failure should not produce duplicates, which is especially important when a comment or review triggers downstream automation.
4. Machine-readable error semantics
Write operations would benefit from stable error codes rather than natural-language messages alone. Example taxonomy:
AUTHORIZATION_REQUIREDPOLICY_DENIEDCLIENT_APPROVAL_REQUIREDCLIENT_APPROVAL_DECLINEDSTALE_STATE_CONFLICTVALIDATION_ERRORNOT_FOUNDALREADY_EXISTSPERMISSION_DENIEDRATE_LIMITEDSERVER_ERROR
The exact set of codes is less important than stable, machine-actionable semantics. Errors should also indicate whether a retry can succeed without a change in state.
Observed friction points
These are secondary to the architectural requests above but provide concrete evidence of the problem.
Inconsistent write-path behaviour
Some write tools (including certain file-update operations) fail with an opaque No approval received while other write paths succeed. Both are write operations, so the difference is hard for an agent to reason about.
If approval requirements differ per operation, they should be discoverable through the tool schema or documentation and reflected clearly in errors, ideally in a machine-discoverable form so autonomous clients can determine in advance whether a workflow is likely to succeed.
Comment tools blocked or opaque
Issue-comment and PR-comment operations can fail with the same message. Please distinguish between:
- Prohibited by policy
- Requires interactive client approval
- User declined an approval prompt
- Host does not support the required approval mechanism
- Insufficient GitHub permissions
- Authentication / authorisation failure
- Other server-side failure
Retrying is only meaningful for some of these.
Impact: When comment tools are unavailable, agents may fall back to commit messages as an audit trail. That degrades exactly the provenance GitHub is being used to provide.
Documentation: It should be explicit which tool posts a top-level PR conversation comment (as opposed to a review comment) and whether issue-comment tools apply to pull requests.
create_branch idempotency
When a branch already exists (common when automation pre-creates it), create_branch fails with Reference already exists. An idempotent option should distinguish:
- Branch exists at the requested target SHA: treat as success and return the existing ref.
- Branch exists at a different SHA: return an explicit conflict.
An idempotent retry should never silently conceal a conflicting branch state.
sha: null semantics
Passing sha: null for new files or updates on feature branches appears to work but is not clearly documented. Please document:
- When it is valid and whether it means "create new file"
- Behaviour when the path already exists
- What concurrency protections apply
- Expected errors
Feedback-channel improvements
The dedicated Insiders feedback template is a good idea. These fields would help triage:
- Specific Insiders feature under evaluation (required)
- Server version/build; remote vs local
- MCP host/client and version; IDE/app and version; OS
- Expected vs actual behaviour
- Impact / severity
- Reproduction steps
- Classification (usability, performance, reliability, documentation, feature design)
- Optional logs, screenshots, or MCP traces
- Relevant tool name and arguments (sensitive data redacted)
This would help separate server defects from host-approval issues and environmental problems.
Framing
This reflects a broader need in agentic GitHub usage: reliable, provenance-preserving access to complete review state together with safe mutation primitives.
A pull request is increasingly best understood as an evolving state machine rather than a collection of independent objects.
Priorities (in order)
- Expose current authoritative PR review state as a coherent object.
- Provide stable review-state / version information.
- Provide thread-aware review operations.
- Provide optimistic-concurrency protection (including post-write state tokens and idempotency) for mutations.
- Provide machine-readable error semantics.
The smaller friction points are manifestations of the same underlying gap: agents need to establish what state they observed, whether it is still current, and whether an intended mutation is safe to apply.
That is the capability gap I would most strongly recommend addressing.
Version: Insiders
Feature:
Recommendation: First-class PR review state and concurrency-safe review workflows for GitHub MCP Server
Feedback:
Context
I use the GitHub MCP Server in agentic workflows where GitHub is not only source control but also the accountability and provenance layer for collaboration between multiple AI agents and humans.
The server is already highly useful. This feedback focuses on capability gaps that force agents to reconstruct authoritative pull-request state from many separate objects and operations, then act on it with no guarantee that the state is still current.
Environment: MCP host/client:
<name + version>· Server:<remote/local, version/build>· Insiders feature under evaluation:<feature>· OS/IDE:<if applicable>Scope note: Some failures below may originate in the MCP host's approval layer rather than the server. I have not isolated which. Part of this request is for error semantics that make that distinction possible. I have not yet reproduced these against an Insiders build.
Core problem: observe → reason → act, without state validation
Agentic workflows follow a recurring pattern:
Today an agent has no reliable guarantee that the state observed at step 1 is still valid at step 3, and no single answer to:
The capabilities below all address that gap.
1. Current authoritative PR review state as a single object
An agent currently assembles review state by stitching together multiple independent calls. That is fragile and makes it hard to distinguish findings that are current from those that are stale, outdated, superseded, or dismissed.
This matters most when:
Requested: one operation that returns the complete current review state, including:
The response should also include a stable review-state generation/snapshot identifier (ETag-style or equivalent) so an agent can later establish that the state it inspected is still current.
2. Thread-aware review operations
First-class operations to:
These should be explicitly thread-aware rather than requiring agents to infer thread identity from individual comments. They should also verify (or supply the information needed to verify) that the thread is still current before any mutation.
3. Optimistic concurrency for writes
Write operations should accept an expected-state token, for example:
If either has changed, the mutation should be refused with a machine-readable conflict rather than silently applied.
Head SHA alone is insufficient: a thread can be resolved, reopened, commented on, or dismissed while the head remains unchanged.
Conflicts should return enough information for a client to determine what changed and whether an automatic retry is safe, for example:
rather than a bare conflict with no state information.
Related requests:
4. Machine-readable error semantics
Write operations would benefit from stable error codes rather than natural-language messages alone. Example taxonomy:
AUTHORIZATION_REQUIREDPOLICY_DENIEDCLIENT_APPROVAL_REQUIREDCLIENT_APPROVAL_DECLINEDSTALE_STATE_CONFLICTVALIDATION_ERRORNOT_FOUNDALREADY_EXISTSPERMISSION_DENIEDRATE_LIMITEDSERVER_ERRORThe exact set of codes is less important than stable, machine-actionable semantics. Errors should also indicate whether a retry can succeed without a change in state.
Observed friction points
These are secondary to the architectural requests above but provide concrete evidence of the problem.
Inconsistent write-path behaviour
Some write tools (including certain file-update operations) fail with an opaque
No approval receivedwhile other write paths succeed. Both are write operations, so the difference is hard for an agent to reason about.If approval requirements differ per operation, they should be discoverable through the tool schema or documentation and reflected clearly in errors, ideally in a machine-discoverable form so autonomous clients can determine in advance whether a workflow is likely to succeed.
Comment tools blocked or opaque
Issue-comment and PR-comment operations can fail with the same message. Please distinguish between:
Retrying is only meaningful for some of these.
Impact: When comment tools are unavailable, agents may fall back to commit messages as an audit trail. That degrades exactly the provenance GitHub is being used to provide.
Documentation: It should be explicit which tool posts a top-level PR conversation comment (as opposed to a review comment) and whether issue-comment tools apply to pull requests.
create_branchidempotencyWhen a branch already exists (common when automation pre-creates it),
create_branchfails withReference already exists. An idempotent option should distinguish:An idempotent retry should never silently conceal a conflicting branch state.
sha: nullsemanticsPassing
sha: nullfor new files or updates on feature branches appears to work but is not clearly documented. Please document:Feedback-channel improvements
The dedicated Insiders feedback template is a good idea. These fields would help triage:
This would help separate server defects from host-approval issues and environmental problems.
Framing
This reflects a broader need in agentic GitHub usage: reliable, provenance-preserving access to complete review state together with safe mutation primitives.
A pull request is increasingly best understood as an evolving state machine rather than a collection of independent objects.
Priorities (in order)
The smaller friction points are manifestations of the same underlying gap: agents need to establish what state they observed, whether it is still current, and whether an intended mutation is safe to apply.
That is the capability gap I would most strongly recommend addressing.