Text of github.github.com › gh-aw › reference › gh-aw-as-mcp-server as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

GH-AW as an MCP Server | GitHub Agentic Workflows

Skip to main content GH-AW as an MCP Server The gh aw mcp-server command exposes GitHub Agentic Workflows CLI commands as MCP tools, allowing chat systems and workflows to manage agentic workflows programmatically. Tool options are selected through named MCP parameters, not CLI flags embedded in workflow names, workflow specifications, or run IDs/URLs. Except for the logs tool’s workflow_name , positional values beginning with - return an invalid-parameters error before the command executes.

The logs tool passes workflow names unchanged after a CLI -- boundary, so names such as -nightly remain valid and cannot override options. For a local workflow file whose name begins with - , use a relative path such as ./-workflow.md . Start the server: Terminal window gh aw mcp-server Or configure for any Model Context Protocol (MCP) host: command : gh args : [ aw , mcp-server ] Configuration Options Section titled “Configuration Options” The compile tool uses a dedicated read-only mode with --no-emit --no-check-update by default: it validates workflows without modifying files, including lock files, diagnostic YAML, action pins, import caches, temporary includes, or .gitattributes .

Remote imports and body-level includes, including nested includes, must already be cached; missing entries produce a validation error instead of downloading files. Container validation only inspects local Docker images and reports missing images without pulling them. Validation uses the newly generated YAML, not stale lock-file contents. Fixes, dry-run compilation, and external scanners require write tools. This stronger MCP mode is separate from ordinary CLI compile --no-emit and validate , which can still populate import caches.

Read-only compilation is not an offline guarantee: resolving an import’s branch or tag to its current SHA can require network access. Workflow-writing tools ( add , update , and fix ) are disabled by default. The operator can enable them and allow compilation to write files at server startup for trusted clients and workflow sources: Terminal window gh aw mcp-server --allow-write-tools The mcp-inspect tool only lists configuration.

It never starts workflow-declared commands or containers, connects to configured HTTP endpoints, or checks secrets, even when --allow-write-tools is enabled. Live discovery remains available through gh aw mcp inspect <workflow> invoked directly by the operator after reviewing and trusting the workflow’s commands, packages, container images, and endpoints. Use --port to run over HTTP/SSE: Terminal window gh aw mcp-server --port 8080 Use --validate-actor to require repository permission checks before exposing log and audit capabilities: Terminal window gh aw mcp-server --validate-actor When validation is enabled, logs , audit , audit-diff , and enabled workflow-writing tools require write, maintain, or admin access.

The server reads GITHUB_ACTOR and GITHUB_REPOSITORY , caches permission results in memory for 1 hour, and never falls back to open access if GITHUB_ACTOR is missing. Both the startup capability gate and actor checks apply to stdio and HTTP/SSE transports. Configuring with GitHub Copilot Agent Section titled “Configuring with GitHub Copilot Agent” Configure GitHub Copilot Agent to use gh-aw MCP server: Terminal window gh aw init This creates .github/workflows/copilot-setup-steps.yml that sets up Go, GitHub CLI, and gh-aw extension before agent sessions start, making workflow management tools available to the agent.

MCP server integration is enabled by default. Use gh aw init --no-mcp to skip MCP configuration. Configuring with Copilot CLI Section titled “Configuring with Copilot CLI” To add the MCP server in the interactive Copilot CLI session, start copilot and run: /mcp add github-agentic-workflows gh aw mcp-server Configuring with VS Code Section titled “Configuring with VS Code” Run gh aw init to configure VS Code Copilot Chat: Terminal window gh aw init This creates .github/mcp.json and .github/workflows/copilot-setup-steps.yml .

MCP server integration is enabled by default; use gh aw init --no-mcp to skip it. Alternatively, create .github/mcp.json manually: { "mcpServers" : { "github-agentic-workflows" : { "type" : " local " , "command" : " gh " , "args" : [ " aw " , " mcp-server " ], "tools" : [ " compile " , " audit " , " logs " , " inspect " , " status " , " audit-diff " , " work-queue " , " health " ] } } } Reload VS Code after making changes.

Configuring with Docker Section titled “Configuring with Docker” If gh is not installed locally, use the ghcr.io/github/gh-aw Docker image. The image ships with the GitHub CLI, gh-aw, and native ShellCheck pre-installed and uses mcp-server as the default command. Strict dry-run compilation keeps ShellCheck validation enabled without requiring Docker-in-Docker; missing required scanners remain errors. { "command" : " docker " , "args" : [ " run " , " --rm " , " -i " , " -e " , " GITHUB_TOKEN " , " -e " , " GITHUB_ACTOR " , " ghcr.io/github/gh-aw:latest " , " mcp-server " ] } Pass your GitHub token via the GITHUB_TOKEN environment variable.

Add --validate-actor to the args array to enforce permission checks based on GITHUB_ACTOR . Available Tools Section titled “Available Tools” The MCP server exposes these workflow-management tools: Tool Purpose Key options Returns status Show workflow and compiled-file status. pattern , jq JSON array with workflow , agent , compiled , status , time_remaining . health Read workflow health, success rates, execution trends, and revision-aware recovery evidence. workflow_name , days , start_date , end_date , threshold , repo , logs_dir JSON summary for all workflows or a detailed report for one workflow. compile Compile Markdown workflows to GitHub Actions YAML with optional static analysis. workflows , strict , fix , zizmor , poutine , actionlint , grant , jq JSON array with workflow , valid , errors , warnings , compiled_file . logs Download and analyze workflow logs with timeout and token guardrails. workflow_name , count , start_date , end_date , engine , firewall , no_firewall , branch , after_run_id , before_run_id , artifacts , timeout , max_tokens , jq JSON envelope with the collected report’s file_path and collection state; continuation parameters are included when available. audit Audit one or more workflow runs; with multiple runs, compare each run to the first. run_ids_or_urls (preferred), run_id , deprecated run_id_or_url , plus artifacts , experiment , variant , jq Single-run JSON audit or multi-run diff JSON. checks Normalize CI check state for a pull request. pr_number , repo JSON with state , required_state , pr_number , head_sha , check_runs , statuses , total_count . mcp-inspect List MCP server configurations without executing or connecting to servers. workflow_file ; server and tool are unsupported and return an error.

Formatted configuration listing. work-queue Read the Git-backed work queue without publishing or changing queue state. operation , repo , branch , and operation-specific selectors or filters The selected CLI operation’s JSON output. add Add workflows from remote repositories to .github/workflows . workflows , number , name Added workflow files. update Update sourced workflows and check for gh-aw updates. workflows , major , force Updated workflow files and version checks. fix Apply automatic codemod-style fixes. workflows , write , list_codemods Dry-run or written fixes.

Workflow and run positional parameters must not start with - ; use the tool’s named parameters for options. For a local workflow filename beginning with - , supply a path prefixed with ./ . The add tool’s name is a filename without an extension, not a path: / , \ , and .. are rejected. Workflow destinations must remain within the selected workflow directory, including when existing files are symlinks. The read-only health tool is available without --allow-write-tools or actor validation.

It uses the se

The rest of this page is on the live site.