Calling External Systems

Lesson 6.1

Accessing external systems

Skills, subagents, commands, and hooks are all about the agent's behavior: what it knows, how it's structured, when work fires. None of them, on their own, let the agent do a single thing outside the conversation. Left alone, a capable agent can reason brilliantly about your Jira ticket and still be unable to read it.

External callout is the other axis. A tool the agent can call is a hand it can extend into a real system: to query a database, open a pull request, post a comment, deploy metadata. There are two ways to hand it one, and the difference is mostly about how much machinery you want.

Lesson 6.2

External Call

Same request, two agents. One has no way out of the chat window; the other has the jira CLI on its path. Watch where each one ends up.

Lesson 6.3

CLIs: the shell you already have

The agent runs in an environment with a shell. That means every command-line tool on that machine is, in effect, a capability, no wiring required. gh reaches GitHub, sf reaches a Salesforce org, jira reaches your backlog, psql reaches a database. Install it, log in once, and the agent gains more external access.

This is where reach meets the primitives you already know. A skill rarely adds a new capability itself; more often it just documents how to drive a CLI the agent already has: which command, in what order, with which flags.

# jira-qa-update/SKILL.md: the how-to for a CLI the agent already has
1. Confirm the CLI is authenticated: jira me
2. Post the results comment: jira comment <KEY> --body "…"
3. Attach the screenshots: jira attach <KEY> ./shots/*.png

Lesson 6.4 · Interactive

Approving what it runs

An external callout through a CLI is powerful precisely because it's the real shell, the same one where rm -rf means what it says. So most agent tools don't just run whatever they like. Before executing a shell command, the agent pauses and shows you the exact line, and you decide: allow it once, always allow that kind, or deny it.

# The agent wants to run a command in your shell:
  rm -rf ./build

  [a] Allow once   [A] Always allow   [d] Deny

That prompt is your safety layer, but it only helps if you can read the command well enough to answer. A read-only ls is nothing to fear; an rm -rfNew to the shell? Here's what it does. rm deletes. -r is "recursive": go into a folder and delete everything inside it, subfolders included. -f is "force": don't ask "are you sure?" before each delete. Together, rm -rf permanently removes whatever files you point it at, with no confirmation and no undo, which is why it's worth a second look before you approve it. with a wildcard, or a curl … | sh that pipes downloaded code straight into a shell, deserves a hard look. The judgment is the same one you'd use before running the command yourself.

Lesson 6.5

MCP servers: the typed protocol

A CLI is text in, text out. That's perfect until you need structured data, managed authentication, a live connection, or tools with real input schemas the agent can't get wrong. That's what MCP (the Model Context Protocol) standardizes: a server exposes a set of tools (actions the agent can call), resources (data it can read), and prompts, all with typed schemas, over one shared protocol.

You connect one by declaring it in config. From then on its tools appear to the agent as first-class functions: described, validated, and callable by name, no shell parsing in between.

// .mcp.json: declare a server; its tools become callable
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "\${GITHUB_TOKEN}" }
    }
  }
}
# now the agent can call tools like create_pull_request(...)
# with a typed schema, no flag-parsing, no guessing.

The trade is machinery for structure. An MCP server is more to set up than dropping a binary on the path, but you get typed tools, centralized auth, and an integration you can reuse across every agent and host that speaks the protocol, instead of re-teaching CLI incantations each time.

Lesson 6.6 · Interactive

An MCP call, end to end

The config is just the setup. This is what happens on a single turn: follow one request as it travels from plain English, through the agent's choice of tool, out to the GitHub MCP server, and back again as a sentence you can read. Six steps: press the button and watch each one land.

Lesson 6.7

Choosing, and combining

The two aren't rivals; they sit at different points on the same effort/durability curve, and they layer with the primitives from the rest of the course.

• Start with a CLI. If a command already does the job, that's your reach. A skill wraps it with the know-how.
• Graduate to MCP when the CLI's text interface starts to fray: brittle parsing, awkward auth, or the same integration copied into five projects.
• Wrap either in a skill so the how is captured once. The external callout is the raw capability; the skill is the procedure.
• Isolate a noisy one in a subagent (e.g. a broad database survey) so its output never floods your main window.

Check

Check your understanding