Using MCPs

Model Context Protocol (MCP) is a standard for AI tool integration, allowing agents to securely connect to external tools, databases, and services. GitHub Agentic Workflows includes built-in GitHub MCP integration and supports custom MCP servers for external services.

Quick Start

Get your first MCP integration running in a few minutes.

Step 1: Add GitHub Tools

Create a workflow file at .github/workflows/my-workflow.md:

---
on:
  issues:
    types: [opened]

permissions:
  contents: read
  issues: read

tools:
  github:
    toolsets: [default]
---

# Issue Analysis Agent

Analyze the issue and provide a summary of similar existing issues.

The toolsets: [default] configuration gives your agentic workflow access to repository, issue, and pull request tools.

Step 2: Compile and Test

gh aw compile my-workflow
gh aw mcp inspect my-workflow

GitHub MCP Server

The GitHub MCP server is built into agentic workflows and provides comprehensive access to GitHub’s API.

Available Toolsets

Toolset	Description	Tools
context	User and team information	get_teams, get_team_members
repos	Repository operations	get_repository, get_file_contents, list_commits
issues	Issue management	list_issues, create_issue, update_issue
pull_requests	PR operations	list_pull_requests, create_pull_request
actions	Workflow runs and artifacts	list_workflows, list_workflow_runs
discussions	GitHub Discussions	list_discussions, create_discussion
code_security	Security alerts	list_code_scanning_alerts
users	User profiles	get_me !, get_user, list_users

When calling list_code_scanning_alerts from workflow prompts, always bound the request with state: open and severity: critical,high.

The default toolset includes context, repos, issues, and pull_requests. In workflows, [default] expands to toolsets that work with GitHub Actions tokens. The users toolset is excluded because those tokens do not support user operations.

Caution

get_me is not usable under the integration token. It returns HTTP 403 in all standard gh-aw runs. Do not call get_me to discover the agent’s identity. Instead, read identity fields directly from the <github-context> block that is injected into every workflow prompt — it contains actor, repository, run_id, and other context values.

Operating Modes

Remote mode (mode: remote) connects to a hosted server with no Docker required. Local mode (mode: local) runs in Docker, enabling version pinning for offline or restricted environments. See Remote vs Local Mode.

The GitHub MCP server always operates read-only. Write operations are handled through safe outputs, which run in a separate permission-controlled job.

Manually Configuring a Custom MCP Server

Caution

Custom MCP servers should be read-only. Write operations must go through safe outputs or Custom Safe Outputs. Ensure your MCP server implements authentication and authorization to prevent unauthorized write access.

Add MCP servers to your workflow’s frontmatter using the mcp-servers: section:

---
on: issues

permissions:
  contents: read

mcp-servers:
  microsoftdocs:
    url: "https://learn.microsoft.com/api/mcp"
    allowed: ["*"]

  notion:
    container: "mcp/notion"
    env:
      NOTION_TOKEN: "${{ secrets.NOTION_TOKEN }}"
    allowed:
      - "search_pages"
      - "get_page"
      - "get_database"
      - "query_database"
---

# Your workflow content here

Custom MCP Server Types

Choose the transport that matches how the server runs: stdio for local commands, containers for packaged local servers, HTTP for remote endpoints, and registry when you want to attach registry metadata to a server definition.

Stdio MCP Servers

Use stdin/stdout communication for Python modules, Node.js scripts, and local executables:

mcp-servers:
  serena:
    command: "uvx"
    args: ["--from", "git+https://github.com/oraios/serena", "serena"]
    allowed: ["*"]

Docker Container MCP Servers

Run containerized MCP servers with environment variables, volume mounts, and network restrictions:

mcp-servers:
  custom-tool:
    container: "mcp/custom-tool:v1.0"
    args: ["-v", "/host/data:/app/data"]  # Volume mounts before image
    entrypointArgs: ["serve", "--port", "8080"]  # App args after image
    env:
      API_KEY: "${{ secrets.API_KEY }}"
    allowed: ["tool1", "tool2"]

network:
  allowed:
    - defaults
    - api.example.com

The container field generates docker run --rm -i <args> <image> <entrypointArgs>.

HTTP MCP Servers

Remote MCP servers accessible via HTTP. Configure authentication using the headers field for static API keys, or the auth field for dynamic token acquisition:

mcp-servers:
  deepwiki:
    url: "https://mcp.deepwiki.com/sse"
    allowed:
      - read_wiki_structure
      - read_wiki_contents
      - ask_question

  authenticated-api:
    url: "https://api.example.com/mcp"
    headers:
      Authorization: "Bearer ${{ secrets.API_TOKEN }}"
    allowed: ["*"]

GitHub Actions OIDC Authentication

For MCP servers that accept GitHub Actions OIDC tokens, use the auth field instead of a static headers value. The gateway acquires a short-lived JWT from the GitHub Actions OIDC endpoint and injects it as an Authorization: Bearer header on every outgoing request.

permissions:
  id-token: write   # required for OIDC token acquisition

mcp-servers:
  my-secure-server:
    url: "https://my-server.example.com/mcp"
    auth:
      type: github-oidc
      audience: "https://my-server.example.com"  # optional; defaults to the server URL
    allowed: ["*"]

The auth.type: github-oidc field is only valid on HTTP servers. The MCP server is responsible for validating the token; the gateway acts as a token forwarder. See MCP Gateway — Upstream Authentication for full specification details.

Registry-based MCP Servers

Reference MCP servers from the GitHub MCP registry (the registry field provides metadata for tooling and is not enforced by gh-aw):

mcp-servers:
  markitdown:
    registry: https://api.mcp.github.com/v0/servers/microsoft/markitdown
    container: "ghcr.io/microsoft/markitdown"
    allowed: ["*"]

MCP Tool Filtering

Use allowed: to expose only the tools a workflow needs, or ["*"] to allow all:

mcp-servers:
  notion:
    container: "mcp/notion"
    allowed: ["search_pages", "get_page"]  # or ["*"] to allow all

The allowed: filter is enforced at the MCP gateway level — the gateway only exposes the listed tools to the agent. This enforcement applies regardless of which AI engine or permission mode is in use.

Shared MCP Configurations

Pre-configured MCP server specifications are available in .github/workflows/shared/mcp/ and can be copied or imported directly:

MCP Server	Import Path	Key Capabilities
Jupyter	shared/mcp/jupyter.md	Execute code, manage notebooks, visualize data
AgentDB	shared/mcp/agentdb.md	Semantic and hybrid retrieval over agent-collected corpora (e.g. discussions, issues), backed by a runtime store at AGENTDB_PATH
Azure Auth (OIDC bridge)	shared/azure-auth.md	Re-authenticate Azure CLI inside the agent sandbox using GitHub OIDC
Azure DevOps MCP (experimental)	shared/mcp/azure-devops.md	Azure DevOps MCP endpoint with org-scoped URL, auth header, and required domains
Azure MCP	shared/mcp/azure.md	Azure MCP server in read-only mode with an explicit tool allowlist
Others	shared/mcp/*.md	AST-Grep, Azure, Brave Search, Context7, DataDog, DeepWiki, Fabric RTI, MarkItDown, Microsoft Docs, Notion, Sentry, Serena, Server Memory, Slack, Tavily

Azure shared imports (OIDC, Azure DevOps, Azure MCP)

Use these shared imports together when your workflow needs Azure CLI auth plus Azure DevOps and Azure MCP tools:

---
permissions:
  contents: read
  id-token: write

imports:
  - uses: shared/azure-auth.md
    with:
      azure-client-id: ${{ vars.AZURE_CLIENT_ID }}
      azure-tenant-id: ${{ vars.AZURE_TENANT_ID }}
  - uses: shared/mcp/azure-devops.md
    with:
      organization: YOUR_ORG

mcp-servers:
  azure:
    command: npx
    args:
      - -y
      - "@azure/mcp@latest"
      - server
      - start
      - --read-only
    allowed:
      - subscription_list
      - subscription_get
      - group_list
      - group_get
      - resource_list
      - resource_get
---

shared/azure-auth.md sets AZURE_CONFIG_DIR=/tmp/gh-aw/agent/.azure and runs az login in a pre-agent step so DefaultAzureCredential can resolve AzureCliCredential inside the sandbox.

Azure DevOps MCP support (shared/mcp/azure-devops.md) is still experimental, and its interfaces and required configuration may change. Set ADO_MCP_AUTH_TOKEN to the full Authorization header value, such as a bearer token string. In diagnostics and inspect output, the header is masked as Authorization: ******; this is expected.

This shared Azure DevOps configuration also requires *.dev.azure.com, *.visualstudio.com, and *.microsoftonline.com in the network allowlist.

Keep the command-based Azure MCP variant read-only with an explicit allowed list; do not switch to allowed: ["*"].

Adding MCP Servers from the Registry

Use gh aw mcp add to browse and add servers from the GitHub MCP registry (default: https://api.mcp.github.com/v0):

gh aw mcp add                                                                    # List available servers
gh aw mcp add my-workflow makenotion/notion-mcp-server                           # Add server
gh aw mcp add my-workflow makenotion/notion-mcp-server --transport stdio         # Specify transport
gh aw mcp add my-workflow makenotion/notion-mcp-server --tool-id my-notion       # Custom tool ID
gh aw mcp add my-workflow server-name --registry https://custom.registry.com/v1  # Custom registry

Practical Examples

Example 1: Basic Issue Triage

---
on:
  issues:
    types: [opened]

permissions:
  contents: read
  issues: read

tools:
  github:
    toolsets: [default]

safe-outputs:
  add-comment:
---

# Issue Triage Agent

Analyze issue #${{ github.event.issue.number }} and add a comment with category, related issues, and suggested labels.

Example 2: Security Audit with Discussions

---
on: weekly on sunday

permissions:
  contents: read
  security-events: read
  discussions: write

tools:
  github:
    toolsets: [default, code_security, discussions]

safe-outputs:
  create-discussion:
    category: "Security"
    title-prefix: "[security-scan] "
---

# Security Audit Agent

Review code scanning alerts and create weekly security discussions with findings.

Debugging and Troubleshooting

Inspect MCP configurations with gh aw mcp inspect my-workflow (add --server <name> --verbose for details) or gh aw mcp list-tools <server> my-workflow.

For advanced debugging, import shared/mcp-debug.md to access diagnostic tools and the report_diagnostics_to_pull_request custom safe-output.

Common issues are usually connection failures, which point to syntax, environment variable, or network problems, or missing tools, which usually mean the toolsets configuration or allowed list needs to be checked with gh aw mcp inspect.

Related Documentation

See MCP Scripts for inline tools without external MCP servers, Tools for the full tools reference, CLI Commands for commands such as mcp inspect, Imports for modular workflow composition, Frontmatter for configuration details, and Workflow Structure for directory layout.

For upstream references, see the Model Context Protocol Specification and the GitHub MCP Server.