Skip to content
GitHub Agentic Workflows

Using MCPs

This guide covers using Model Context Protocol (MCP) servers with GitHub Agentic Workflows.

What is MCP?

Section titled “What is MCP?”

Model Context Protocol (MCP) is a standardized protocol that allows AI agents to securely connect to external tools, databases, and services. GitHub Agentic Workflows uses MCP to integrate databases and APIs, extend AI capabilities with specialized functionality, maintain standardized security controls, and enable composable workflows by mixing multiple MCP servers.

Quick Start

Section titled “Quick Start”

Basic MCP Configuration

Section titled “Basic MCP Configuration”

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

---
on: issues


permissions:
  contents: read
  issues: write


engine: claude


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

Adding MCP Servers from the Registry

Section titled “Adding MCP Servers from the Registry”

The easiest way to add MCP servers is using the GitHub MCP registry with the gh aw mcp add command:

Terminal window
# List available MCP servers from the registry
gh aw mcp add


# Add a specific MCP server to your workflow
gh aw mcp add my-workflow makenotion/notion-mcp-server


# Add with specific transport preference
gh aw mcp add my-workflow makenotion/notion-mcp-server --transport stdio


# Add with custom tool ID
gh aw mcp add my-workflow makenotion/notion-mcp-server --tool-id my-notion


# Use a custom registry
gh aw mcp add my-workflow server-name --registry https://custom.registry.com/v1

This automatically searches the registry (default: https://api.mcp.github.com/v0), adds server configuration, and compiles the workflow.

Engine Compatibility

Section titled “Engine Compatibility”

All AI engines support the full range of MCP features:

  • Copilot (default): ✅ Full MCP support (stdio, Docker, HTTP)
  • Claude: ✅ Full MCP support (stdio, Docker, HTTP)
  • Codex (experimental): ✅ Full MCP support (stdio, Docker, HTTP)

MCP Server Types

Section titled “MCP Server Types”

1. Stdio MCP Servers

Section titled “1. Stdio MCP Servers”

Direct command execution with 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"
      - "start-mcp-server"
      - "--context"
      - "codex"
      - "--project"
      - "${{ github.workspace }}"
    allowed: ["*"]

2. Docker Container MCP Servers

Section titled “2. Docker Container MCP Servers”

Containerized MCP servers for third-party tools, complex dependencies, and security isolation:

mcp-servers:
  ast-grep:
    container: "mcp/ast-grep"
    version: "latest"
    allowed: ["*"]

The container field generates command "docker" with args ["run", "--rm", "-i", "mcp/ast-grep:latest"]. Specify version separately or include it in the container field (e.g., container: "mcp/ast-grep:latest").

Container Arguments and Entrypoint Arguments

Section titled “Container Arguments and Entrypoint Arguments”

Specify arguments before (args) or after (entrypointArgs) the container image following the pattern: docker run [args] image:tag [entrypointArgs]

Example with volume mounts and application arguments:

mcp-servers:
  custom-tool:
    container: "mcp/custom-tool"
    version: "v1.0"
    args:
      - "-v"
      - "/host/data:/app/data"
    entrypointArgs:
      - "serve"
      - "--port"
      - "8080"
      - "--verbose"
    allowed: ["*"]

This generates:

docker run --rm -i -v /host/data:/app/data mcp/custom-tool:v1.0 serve --port 8080 --verbose

Example with read-only mode (like the Azure MCP Server):

mcp-servers:
  azure:
    container: "mcr.microsoft.com/azure-sdk/azure-mcp"
    version: "latest"
    entrypointArgs:
      - "server"
      - "start"
      - "--read-only"
    env:
      AZURE_TENANT_ID: "${{ secrets.AZURE_TENANT_ID }}"
      AZURE_CLIENT_ID: "${{ secrets.AZURE_CLIENT_ID }}"
      AZURE_CLIENT_SECRET: "${{ secrets.AZURE_CLIENT_SECRET }}"
    allowed: ["*"]

This generates:

docker run --rm -i -e AZURE_TENANT_ID -e AZURE_CLIENT_ID -e AZURE_CLIENT_SECRET \
  mcr.microsoft.com/azure-sdk/azure-mcp:latest server start --read-only

Custom Docker Configuration

Section titled “Custom Docker Configuration”

For advanced use cases, you can configure Docker containers with environment variables and network restrictions:

mcp-servers:
  context7:
    container: "mcp/context7"
    env:
      CONTEXT7_API_KEY: "${{ secrets.CONTEXT7_API_KEY }}"
    network:
      allowed:
        - mcp.context7.com
    allowed:
      - get-library-docs
      - resolve-library-id

This generates a Docker container with environment variables and network egress controls:

  • Command: "docker"
  • Args: Includes environment variable flags (e.g., -e CONTEXT7_API_KEY) and network proxy configuration
  • Network: Squid proxy restricts egress to allowed domains only

Configure environment variables (env:), Docker arguments (args:), application arguments (entrypointArgs:), network egress controls (network.allowed:), and accessible tools (allowed:). See Container Arguments and Entrypoint Arguments and Network Egress Permissions.

3. HTTP MCP Servers

Section titled “3. HTTP MCP Servers”

Remote MCP servers accessible via HTTP for cloud services, remote APIs, and shared infrastructure:

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


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

4. Registry-based MCP Servers

Section titled “4. Registry-based MCP Servers”

Reference MCP servers from the GitHub MCP registry (the registry field provides metadata for tooling):

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

GitHub MCP Integration

Section titled “GitHub MCP Integration”

GitHub Agentic Workflows includes built-in GitHub MCP integration with comprehensive repository access. See Tools for details.

Configure the Docker image version (default: "sha-09deac4"):

tools:
  github:
    version: "sha-09deac4"
    toolset: [default, actions]  # Recommended: use toolsets

GitHub Authentication

Section titled “GitHub Authentication”

Token precedence: GH_AW_GITHUB_TOKEN (highest priority) or GITHUB_TOKEN (fallback).

Tool Allow-listing

Section titled “Tool Allow-listing”

Control which MCP tools are available with allowed: (Claude engine support):

Specific tools:

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

Generates: mcp__deepwiki__read_wiki_structure, mcp__deepwiki__read_wiki_contents

Wildcard access:

mcp-servers:
  ast-grep:
    container: "mcp/ast-grep"
    allowed: ["*"]

Generates: mcp__ast-grep (all tools)

HTTP Headers

Section titled “HTTP Headers”

Configure authentication in URL parameters (e.g., ?apiKey=${{ secrets.API_KEY }}) or use dedicated header fields when needed.

Network Egress Permissions

Section titled “Network Egress Permissions”

Restrict outbound access for containerized stdio MCP servers with network.allowed:

mcp-servers:
  context7:
    container: "mcp/context7"
    env:
      CONTEXT7_API_KEY: "${{ secrets.CONTEXT7_API_KEY }}"
    network:
      allowed:
        - mcp.context7.com
    allowed:
      - get-library-docs

Enforcement uses a Squid proxy configured with HTTP_PROXY/HTTPS_PROXY and iptables rules to block non-allowed domains. Only applies to containerized stdio servers (not HTTP or non-container stdio).

Available Shared MCP Configurations

Section titled “Available Shared MCP Configurations”

The gh-aw repository includes pre-configured shared MCP server workflows in .github/workflows/shared/mcp/:

Jupyter Notebook Integration

Section titled “Jupyter Notebook Integration”

Execute code in Jupyter notebooks and visualize data:

imports:
  - shared/mcp/jupyter.md

Provides tools for executing cells, managing notebooks, and retrieving outputs. Includes self-hosted JupyterLab service with Docker services support.

Drain3 Log Analysis

Section titled “Drain3 Log Analysis”

Mine log patterns and extract structured templates from unstructured log files:

imports:
  - shared/mcp/drain3.md

Provides 8 tools including index_file, list_clusters, find_anomalies, compare_runs, and search_pattern for log template mining and pattern analysis.

Other Available Servers

Section titled “Other Available Servers”

Additional shared MCP configurations include: AST-Grep, Azure, Brave Search, Context7, DataDog, DeepWiki, Fabric RTI, MarkItDown, Microsoft Docs, Notion, Sentry, Serena, Server Memory, Slack, and Tavily. Browse .github/workflows/shared/mcp/ for complete list with documentation.

Debugging and Troubleshooting

Section titled “Debugging and Troubleshooting”

Use CLI commands to inspect and debug MCP configurations:

Terminal window
# Inspect MCP servers in workflow
gh aw mcp inspect my-workflow
gh aw mcp inspect my-workflow --server trello-server --verbose


# List available tools
gh aw mcp list-tools notion my-workflow


# Launch MCP inspector
gh aw mcp inspect my-workflow --inspector

For MCP server troubleshooting, import the mcp-debug shared workflow:

imports:
  - shared/mcp-debug.md

This provides diagnostic tools and the report_diagnostics_to_pull_request custom safe-output for posting diagnostic findings to pull requests.

Common issues:

  • Connection failures: Verify configuration syntax, environment variables, and network connectivity
  • Tool not found: Add tool to allowed list and verify spelling with gh aw mcp inspect
Section titled “Related Documentation”

External Resources

Section titled “External Resources”