Tools & MCP: Real Capabilities, Governed

By the end of this chapter you can give the Repo Assistant real capabilities — querying GitHub, fetching web pages, running shell commands, calling third-party services — through the tools: block and MCP servers, while keeping every capability governed by the security model from Chapter 7.

Everything targets gh aw v0.81.6. We hand the Repo Assistant its first real tools and watch it do a richer triage than prose alone allows.

A language model on its own can only reason about the text in front of it. To be useful on your repo it needs to act on the world: look up related issues, read a linked spec, run a linter, query a service. Those actions are tools — the bridge between the model's judgment and real systems.

The industry-standard way to expose a tool to an agent is the Model Context Protocol (MCP): an open protocol that lets an agent discover and call capabilities offered by a “server” — a GitHub server, a database server, a browser server. MCP is why the same workflow can talk to wildly different systems through one uniform interface.

The tension: capability vs. exposure

Every tool you add is also new attack surface. A tool that reads private data feeds the second leg of the lethal trifecta; a tool that reaches the network feeds the third. A naive “give the agent everything” approach maximizes usefulness and risk together. So the discipline is the same as with permissions: grant the fewest tools the task needs, each scoped as tightly as possible — and lean on gh-aw to sandbox what you do grant.

Capabilities are declared in the tools: block, which specifies “which GitHub API calls, browser automation, and AI capabilities are available to your workflow” (Tools).

Built-in tools

A handful ship with gh-aw. The most common:

bash is a good illustration of scoping: it “defaults to safe commands” and you narrow or widen it explicitly — bash: ["echo", "git status"] for a specific set, or bash: [] to disable it entirely (Tools). Grant bash: [":*"] (everything) only with real caution.

Custom MCP servers

For anything beyond the built-ins, declare an MCP server under mcp-servers: — “custom Model Context Protocol servers for third-party services” (Tools):

mcp-servers:
  slack:
    command: "npx"
    args: ["-y", "@slack/mcp-server"]
    env:
      SLACK_BOT_TOKEN: "${{ secrets.SLACK_BOT_TOKEN }}"
    allowed: ["send_message", "get_channel_history"]   # only these tools

A server can be a process (command+args), a Docker container, or an HTTP url; env passes secrets, and allowed restricts which of its tools the agent may call (Tools).

The MCP gateway sandbox

Here's the safety story that makes third-party servers acceptable. MCP servers don't run in the agent's process — they “execute within isolated containers, enforcing substrate-level separation between the agent and each server.” A gateway spawns them, “while AWF mediates all network egress” so “even if an MCP server is compromised, it cannot access the memory or state of other components” (Security Architecture). The allowed: list is enforced at the gateway, and per-server network allowlists still apply.

Add a tool when the task genuinely can't be done without it — and stop there. The question to ask of every tool is: “if the agent were hijacked, what could it do with this?”

When not to

• Don't grant bash: [":*"] casually. Unrestricted shell is close to unrestricted power. Allowlist exactly the commands the task runs.
• Don't add an MCP server you haven't vetted. A third-party server is code you're running; the gateway isolates it, but a malicious one can still misuse the tools and network you grant it. Pin it, scope its allowed tools, and limit its network.
• Don't widen the network just to make a tool work. A tool that needs broad egress reopens the exfiltration leg you closed in Chapter 7. Add only the specific domains it requires.
• Don't confuse tools with writes. Tools are how the agent reads and acts in-run; persistent changes to your repo still belong in safe-outputs:. Keep the two separate.

Let's give the Repo Assistant its first real capabilities. It will query the GitHub MCP server to find duplicate issues and use web-fetch to read a linked spec — a much richer triage than reading the issue text alone.

permissions:
  contents: read
  issues: read
engine: copilot
network:
  allowed:
    - defaults
    - github
tools:
  github:
    toolsets: [issues, repos]   # the GitHub MCP server, read-only
  web-fetch:                     # fetch linked docs (firewall-gated)
safe-outputs:
  add-comment:
    max: 1

The github tool is an MCP server — the same GitHub MCP the security docs describe, scoped here to just the issues and repos toolsets so the agent can search but not, say, manage releases. web-fetch is gated by the network: firewall from Chapter 7: the agent can only reach domains you've allowed, so a link to an untrusted host simply won't load. Every capability is present and bounded.

Notice what stayed constant: permissions: are still read-only, and the only way anything reaches the repo is the single add-comment safe output. We added reach, not write authority.

gh aw compile examples/ch08/repo-assistant-tools.md
# ✓ examples\ch08\repo-assistant-tools.md (100.8 KB)
# ✓ Compiled 1 workflow(s): 0 error(s), 0 warning(s)

You can now give an agent real capabilities without widening its blast radius:

• Agents need tools to act; MCP is the open protocol that exposes capabilities uniformly — but every tool is also attack surface.
• The tools: block grants built-in tools (github, bash, edit, web-fetch, playwright…); mcp-servers: adds custom servers with an allowed tool list.
• The MCP gateway runs each server in an isolated container, with AWF mediating egress — a compromised server can't reach other components.
• Grant the fewest tools, scoped tightest; never reach for unrestricted bash or a broad network; keep tools (reads/actions) separate from safe-outputs: (writes).

What's next. That completes the machinery — triggers, engines, safe outputs, security, tools. In Part II's payoff, we assemble it into production-shaped patterns. Chapter 9: Continuous Triage & Docs ships two mini-products the Repo Assistant runs on its own.