Skip to content

[docs] docs: unbloat guides/mcps.md #22826

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pelikhan merged 1 commit into from
Mar 25, 2026
Merged

[docs] docs: unbloat guides/mcps.md #22826

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 13 additions & 53 deletions docs/src/content/docs/guides/mcps.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,19 +5,11 @@ sidebar:
order: 4
---

This guide covers using custom [Model Context Protocol](/gh-aw/reference/glossary/#mcp-model-context-protocol) servers with GitHub Agentic Workflows.

[Model Context Protocol](/gh-aw/reference/glossary/#mcp-model-context-protocol) (MCP, a standard for AI tool integration) 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.

GitHub Agentic Workflows includes built-in GitHub MCP integration with comprehensive repository access. See [GitHub Tools](/gh-aw/reference/github-tools/) for details. This guide focuses on using custom MCP servers to connect to external services and databases.
[Model Context Protocol](/gh-aw/reference/glossary/#mcp-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 (see [GitHub Tools](/gh-aw/reference/github-tools/)); this guide covers adding custom MCP servers for external services.

> [!IMPORTANT]
>
> The design philosophy of GitHub Agentic Workflows is to provide a secure, standardized way for AI agents to interact with external systems. For custom MCP servers, the design intention is that they only be used for **read-only** access to external tools, databases, and APIs. This allows AI agents to retrieve information, perform analysis, and generate insights based on external data while maintaining a strong security posture.
>
> Write operations should be performed through [afe outputs](/gh-aw/reference/safe-outputs/), including [Custom Safe Outputs](/gh-aw/reference/custom-safe-outputs/) for scenarios not covered by default safe outputs.
>
> It is your responsibility to ensure that any custom MCP servers you integrate are designed and configured in a way that prevents unauthorized write operations. This includes implementing appropriate authentication, authorization, and input validation mechanisms on your MCP server to enforce read-only access and protect against potential abuse.
> Custom MCP servers should be **read-only**. Write operations must go through [safe outputs](/gh-aw/reference/safe-outputs/) or [Custom Safe Outputs](/gh-aw/reference/custom-safe-outputs/). Ensure your MCP server implements authentication and authorization to prevent unauthorized write access.

## Manually Configuring a Custom MCP Server

Expand Down Expand Up @@ -69,10 +61,6 @@ Run containerized MCP servers with environment variables, volume mounts, and net

```yaml wrap
mcp-servers:
ast-grep:
container: "mcp/ast-grep:latest"
allowed: ["*"]

custom-tool:
container: "mcp/custom-tool:v1.0"
args: ["-v", "/host/data:/app/data"] # Volume mounts before image
Expand All @@ -84,43 +72,31 @@ mcp-servers:
network:
allowed:
- defaults
- api.example.com # Restricts egress to allowed domains
- api.example.com
```

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

### HTTP MCP Servers

Remote MCP servers accessible via HTTP for cloud services, remote APIs, and shared infrastructure:
Remote MCP servers accessible via HTTP. Configure authentication headers using the `headers` field:

```yaml wrap
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
```

HTTP MCP servers must implement the MCP specification over HTTP. Configure authentication headers using the `headers` field:

```yaml wrap
mcp-servers:
authenticated-api:
url: "https://api.example.com/mcp"
headers:
Authorization: "Bearer ${{ secrets.API_TOKEN }}"
X-Custom-Header: "value"
allowed: ["*"]
```

Headers are injected into all HTTP requests made to the MCP server, enabling bearer token authentication, API keys, and other custom authentication schemes.

### Registry-based MCP Servers

Reference MCP servers from the GitHub MCP registry (the `registry` field provides metadata for tooling):
Expand All @@ -135,20 +111,18 @@ mcp-servers:

## MCP Tool Filtering

For custom MCP servers, use `allowed:` to specify which tools are available:
Use `allowed:` to specify which tools are available, or `["*"]` to allow all:

```yaml wrap
mcp-servers:
notion:
container: "mcp/notion"
allowed: ["search_pages", "get_page"] # Limit to specific tools
allowed: ["search_pages", "get_page"] # or ["*"] to allow all
```

Use `["*"]` to allow all tools from a custom MCP server.

## Shared MCP Configurations

Pre-configured MCP server specifications are available in the GitHub Agentics Workflow repository [`.github/workflows/shared/mcp/`](https://github.com/github/gh-aw/tree/main/.github/workflows/shared/mcp) for common tools and services. These can be copied into your own workflows or imported directly. Examples include:
Pre-configured MCP server specifications are available in [`.github/workflows/shared/mcp/`](https://github.com/github/gh-aw/tree/main/.github/workflows/shared/mcp) and can be copied or imported directly. Examples include:

| MCP Server | Import Path | Key Capabilities |
|------------|-------------|------------------|
Expand All @@ -158,27 +132,16 @@ Pre-configured MCP server specifications are available in the GitHub Agentics Wo

## 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:
Use `gh aw mcp add` to browse and add servers from the GitHub MCP registry (default: `https://api.mcp.github.com/v0`):
Copy link

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The default MCP registry URL here is documented as https://api.mcp.github.com/v0, but the CLI/codebase defaults to https://api.mcp.github.com/v0.1 (see pkg/constants/constants.go and pkg/cli/mcp_add.go). Please update the docs to match the actual default to avoid users pointing at the wrong registry endpoint.

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

Copilot uses AI. Check for mistakes.

```bash wrap
# 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
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
```

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

## Debugging and Troubleshooting

Inspect MCP configurations with CLI commands: `gh aw mcp inspect my-workflow` (add `--server <name> --verbose` for details) or `gh aw mcp list-tools <server> my-workflow`.
Expand All @@ -195,8 +158,5 @@ For advanced debugging, import `shared/mcp-debug.md` to access diagnostic tools
- [Imports](/gh-aw/reference/imports/) - Modularizing workflows with includes
- [Frontmatter](/gh-aw/reference/frontmatter/) - All configuration options
- [Workflow Structure](/gh-aw/reference/workflow-structure/) - Directory organization

## External Resources

- [Model Context Protocol Specification](https://github.com/modelcontextprotocol/specification)
- [GitHub MCP Server](https://github.com/github/github-mcp-server)
Loading