MCP Server

The gh aw mcp-server command exposes CLI tools (status, compile, logs, audit, mcp-inspect) to AI agents through the Model Context Protocol.

Start the server:

gh aw mcp-server

Or configure for any MCP host:

command: gh
args: [aw, mcp-server]

Configuration Options

Custom Command Path

Use --cmd to specify a custom binary path for local development, CI/CD, or environments without the gh CLI extension:

gh aw mcp-server --cmd ./gh-aw

HTTP Server Mode

Run with HTTP/SSE transport using --port:

gh aw mcp-server --port 8080

Configuring with GitHub Copilot Agent

Configure GitHub Copilot Agent to use gh-aw MCP server:

gh aw init --mcp

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.

Configuring with Copilot CLI

Add the MCP server to GitHub Copilot CLI:

/mcp add github-agentic-workflows gh aw mcp-server

Configuring with VS Code

Configure VS Code Copilot Chat to use gh-aw MCP server:

gh aw init --mcp

This creates .vscode/mcp.json and .github/workflows/copilot-setup-steps.yml.

Alternatively, create .vscode/mcp.json manually:

{
  "servers": {
    "github-agentic-workflows": {
      "command": "gh",
      "args": ["aw", "mcp-server"],
      "cwd": "${workspaceFolder}"
    }
  }
}

Reload VS Code after making changes.

Available Tools

The MCP server provides:

status: List workflows with pattern filter
compile: Generate GitHub Actions YAML
logs: Download with timeout handling and continuation
audit: Generate report to /tmp/gh-aw/aw-mcp/logs
add: Install workflows from remote repositories
mcp-inspect: Inspect servers and validate secrets

Logs Tool Features

Timeout and Continuation: Uses 50-second timeout for large runs. Returns partial results with continuation field containing before_run_id to resume fetching.

Output Size Guardrail: Default 12,000 tokens (~48KB) limit. Customize with max_tokens parameter. When triggered, provides jq queries for filtering (e.g., '.runs | map(select(.conclusion == "failure"))').

Large Output Handling: Outputs exceeding 16,000 tokens (~64KB) are written to /tmp/gh-aw/safe-outputs/ with file location and schema description returned.

Using as Agentic Workflows Tool

Enable in workflow frontmatter:

---
tools:
  agentic-workflows:
---

Check workflow status, download logs, and audit failures.