gh-aw MCP server exposes 8 CLI tools but not `checks`, forcing review workflows to shell out to `gh aw checks`

[samuelkahessay]

gh-aw version: v0.66.1
Discovered: 2026-04-05
Category: MCP tool coverage / workflow DX
Severity: Medium

What happens

gh-aw already ships an MCP server (agentic-workflows) that wraps several gh aw CLI commands so agents can use them without depending on authenticated shell access. In v0.66.1, that MCP server exposes exactly 8 tools:

• status
• compile
• logs
• audit
• mcp-inspect
• add
• update
• fix

But it does not expose checks, even though gh aw checks <PR_NUMBER> --json is the gh-aw-native way to normalize CI state for a pull request.

That leaves review-style workflows in an awkward split state:

1. GitHub reads like PR diff / PR metadata / issue metadata can be done through GitHub MCP.
2. gh-aw's own normalized PR check classification still requires a shell command: gh aw checks.
3. On private repos, that shell path requires GitHub CLI auth, which is exactly the path that becomes brittle inside agent bash.

In our aurrin-platform review workflow, gh aw checks was the only remaining gh-aw-specific shell dependency in the prompt. If checks were available through MCP, the workflow could stay MCP-first for GitHub operations and drop this dependency entirely.

What should happen

The gh-aw MCP server should expose checks as a first-class MCP tool.

That gives workflows a single auth model for:

• GitHub reads via GitHub MCP
• gh-aw workflow introspection via agentic-workflows MCP

...without forcing agents to shell out to gh aw checks from bash.

Where in the code

• Upstream pkg/cli/checks_command.go:71-100 defines the CLI command: checks <pr-number>, including the normalized states (success, failed, pending, no_checks, policy_blocked).
• Upstream pkg/cli/checks_command.go:122-170 implements RunChecks / FetchChecksResult.
• Upstream pkg/cli/mcp_server.go:56-78 registers the MCP server tools. checks is absent from the registry.
• Upstream pkg/cli/mcp_server_command.go:27-41 documents the MCP server's tool list. checks is absent there too.
• Upstream docs/src/content/docs/reference/gh-aw-as-mcp-server.md:105-180 lists the available MCP tools and also omits checks.
• Upstream .github/aw/debug-agentic-workflow.md:90-99 explicitly tells users to use MCP equivalents instead of unauthenticated gh aw CLI commands, but the list stops at status, compile, logs, audit, update, add, and mcp-inspect. There is no equivalent listed for gh aw checks.

Evidence

Concrete workflow need

aurrin-platform/.github/workflows/pr-review-agent.md instructs the agent to:

• read PR / issue data
• then run gh aw checks <PR_NUMBER> --json

The GitHub-read operations can be served by GitHub MCP. gh aw checks cannot, because the gh-aw MCP server does not expose it.

The CLI command exists

In v0.66.1, pkg/cli/checks_command.go already implements:

• gh aw checks 42
• gh aw checks 42 --repo owner/repo
• gh aw checks 42 --json

So this is not a missing backend capability. It is a missing MCP registration / docs surface.

The MCP server omits it

Both the code (pkg/cli/mcp_server.go) and the MCP docs (reference/gh-aw-as-mcp-server.md) enumerate the same 8 tools and do not include checks.

Why this mattered in production

Observed in a private same-repo review run on 2026-04-05.

That run hit the familiar "gh CLI is not authenticated" path in agent bash. The broader bash-auth problem is not the main finding here; the key point is that one of the commands the workflow legitimately needed to run was gh aw checks, and there was no MCP alternative available.

If checks were mounted through the gh-aw MCP server, this workflow could use MCP for all gh-aw-specific reads and no longer depend on bash for that operation.

Proposed fix

Minimal upstream fix:

1. Add a registerChecksTool(server, execCmd) MCP registration following the same pattern as the existing status, compile, logs, audit, mcp-inspect, add, update, and fix registrations.
2. Document the new tool in docs/src/content/docs/reference/gh-aw-as-mcp-server.md.
3. Update auth-troubleshooting / authoring docs that currently say "use the MCP equivalent instead of unauthenticated gh aw" so checks is included in that list.

Once that exists, review workflows like ours can:

• use GitHub MCP for PR / issue reads
• use agentic-workflows.checks for normalized CI state
• avoid gh aw checks in bash entirely

Impact

Medium. This is a gap in tool coverage, not a total framework failure. But it lands in a sharp place: review-style workflows frequently need gh-aw's own normalized view of PR checks, and right now the only path is shelling out to gh aw checks.

On private repos, that pushes workflows toward bash auth plumbing or pre-step workarounds for a capability gh-aw already has internally. Adding checks to the MCP surface would delete the need for that workaround in this class of workflows.

Related upstream issues

• #22703 (closed, completed) — GitHub CLI unauthenticated on Action runs. Likely triage confusion point. That issue was closed with an MCP-first resolution. This finding is the concrete reason that answer is incomplete for review workflows: MCP still lacks checks.
• #24682 (closed, completed) — [plan] Document pre-step data-fetching pattern in create-agentic-workflow.md. Useful workaround context, not a dupe. Current upstream docs now include a pre-step pattern with per-step GH_TOKEN, which lowers the severity of the old bash-auth framing, but it does not close this MCP tool-gap. A missing MCP checks tool still forces that workaround for a capability gh-aw already implements.

I did not find an existing upstream issue specifically covering "gh-aw MCP server is missing the checks command even though the CLI implements it."