Text of github.github.com › gh-aw › guides › mcps 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

Using MCPs | GitHub Agentic Workflows

Skip to main content 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 Section titled “Quick Start” Get your first MCP integration running in a few minutes. 1. Add GitHub Tools Section titled “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. 2. Compile and Test Section titled “2.

Compile and Test” Terminal window gh aw compile my-workflow gh aw mcp inspect my-workflow GitHub MCP Server Section titled “GitHub MCP Server” The GitHub MCP server is built into agentic workflows and provides read-only access to GitHub’s API. Write actions still go through safe outputs . Available Toolsets Section titled “Available Toolsets” Toolset Purpose Example 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 The default toolset includes context , repos , issues , and pull_requests .

It expands to the toolsets supported by GitHub Actions tokens, so users is excluded. When calling list_code_scanning_alerts from workflow prompts, always bound the request with state: open and severity: critical,high . Operating Modes Section titled “Operating Modes” Use mode: remote to connect to the hosted server with no Docker requirement. Use mode: local to run in Docker when you need local version pinning or support for restricted environments.

See Remote vs Local Mode . Manually Configuring a Custom MCP Server Section titled “Manually Configuring a Custom MCP Server” 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 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. Migrate dynamic configuration values Section titled “Migrate dynamic configuration values” Treat MCP URLs, arguments, mounts, headers and environment values as data, not shell scripts. Actions expressions such as ${{ steps.setup.outputs.port }} are transported through environment bindings and resolved after JSON parsing.

This also applies to entrypoints, container versions, registry metadata, proxy arguments, allowed tools and built-in GitHub custom arguments. CA paths retain their restricted workspace/temp expression support; unsupported expressions fail before lock emission. Simple runner $NAME and ${NAME} references remain supported. Replace shell computations such as $(...) , backticks and ${NAME:-default} with a setup-step output or an equivalent Actions expression.

For example, when WORKSPACE_FALLBACK is available in the Actions env context, replace ${WORKSPACE_FALLBACK:-/tmp} with: mcp-servers : service : url : https://example.com/mcp headers : X-Workspace : " ${{ env.WORKSPACE_FALLBACK || '/tmp' }} " Compilation warns at configuration paths containing unsupported shell computations. These computations remain literal in both JSON configuration and mount allowlist exports. Former heredoc escapes such as \$(printf literal) and escaped backticks retain their literal payload without the shell-escape backslash.

Compilation rejects a value that combines transported expressions or runner variables with an explicitly deferred gateway reference such as \${TOKEN} . When all inputs are available to the runner, combine them in a single Actions expression; otherwise keep gateway-only references in a separate configuration value. Do not assume a gateway variable is available in the runner’s environment. For inline expressions in shell steps, preview source migrations with gh aw fix <workflow> , review the diff after applying --write , and recompile.

The codemod migrates expanding heredoc bodies, including hash-prefixed lines, but preserves proven quoted bodies and shell comments. CTR-006 still rejects prohibited expressions in those preserved regions because Actions interpolates them before Bash parses the script; remove expressions from comments, and manually move heredoc values to env: and use an unquoted heredoc so Bash expands the shell variable. An unproven heredoc boundary requires a manual fix before any changes to that workflow are written.

Ordinary single-quoted shell strings still require manual quote review; quoted heredocs are not a safe transport for arbitrary multiline Actions values. Deploy regenerated locks with the matching setup runtime. Recompilation does not repair earlier runs, and compiler-owned GH_AW_MCP_* placeholders are not authored configuration. Custom MCP Server Types Section titled “Custom MCP Server Types” Choose the transport that matches how the server runs: command for local executables over stdio container for packaged local servers url for remote HTTP endpoints registry when you want to attach registry metadata to a server definition Stdio MCP Servers Section titled “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 Section titled “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 Section titled “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 Section titled “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:/

The rest of this page is on the live site.