Mastery Module 19 · Agentic Engineering

MCP: Extending Your Agent

Updated

Advanced

What you'll learn

~20 min
  • Explain what MCP servers expose and how transports work
  • Add, inspect, and use an MCP server in your CLI tool
  • Vet a third-party server before connecting it to your codebase

You’re deep in a feature, and you ask your agent: “Summarize the open issues blocking this release.” The agent stalls — it has no way to reach GitHub. You copy-paste issue titles from the browser, paste them in, and repeat. That friction is the exact problem MCP solves. With the GitHub MCP server connected, the same prompt just works — the agent queries the API, reads the issues, and writes the summary.

What MCP is

Model Context Protocol is an open protocol for connecting agents to external tools and data. Anthropic published the original spec, then donated it to the Agentic AI Foundation under the Linux Foundation in December 2025. It is vendor-neutral and community-governed — no single company controls it.

A server exposes three primitives:

PrimitiveWhat it is
ToolsActions the agent can invoke (create PR, run query, send message)
ResourcesData the agent can read (files, API responses, database records)
PromptsPre-built prompt templates the server can contribute

Transports: Local servers run as child processes and communicate over stdio — your machine, no network hop. Remote servers speak HTTP, typically behind an auth layer. Both are supported; your config just points the client at the right endpoint.

Protocol version: the current spec revision is 2026-07-28, which made MCP requests stateless and self-contained. SDK versions moved with it, but not uniformly. As of 2026-11-07, Python’s mcp package is at 2.3.0. TypeScript has two lines: the 2.x SDK ships as split packages (@modelcontextprotocol/server, @modelcontextprotocol/client, 2.4.0), while the original @modelcontextprotocol/sdk package stays on 1.x (1.32.2). You don’t need these internals to use servers, but the split is worth knowing: a TypeScript tutorial importing @modelcontextprotocol/sdk is using the 1.x package, which still works; newer code imports @modelcontextprotocol/server.

As of 2026-11-07, the official MCP Registry lists 58,428 latest-version server records. That counts published entries, not vetted or widely used servers. Claude Code, Codex CLI, Copilot CLI, Cursor, VS Code, Antigravity (agy), and ChatGPT all support MCP. It has become the de-facto standard for agent extensibility.

Hands-on: connect the GitHub MCP server

The GitHub MCP server is the cleanest worked example — official vendor, active maintenance, widely used. The flow below uses Claude Code; the concept is identical for other tools.

Step 1: Get a GitHub token

The server needs a GitHub personal access token. GitHub’s README lists repo for repository work and read:org for team access; grant only the scopes you need. Create one at github.com → Settings → Developer settings → Personal access tokens. In enterprise or government orgs where classic PATs are restricted, prefer OAuth/SSO or fine-grained short-lived tokens.

Store it in your environment — never hardcode it anywhere:

Terminal window
export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_your_token_here"

Add that export to your ~/.bashrc or ~/.zshrc so it persists.

Step 2: Register the server

Claude Code’s mcp add command registers a server. The exact argument syntax varies by transport and server, so run claude mcp add --help to see current flags before using it. For the GitHub server (stdio transport, run from GitHub’s Docker image ghcr.io/github/github-mcp-server) the general pattern is:

Terminal window
claude mcp add --help # read the current flags first
claude mcp add github --scope project \
-e 'GITHUB_PERSONAL_ACCESS_TOKEN=${GITHUB_PERSONAL_ACCESS_TOKEN}' \
-- docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server

Everything after -- is the command that starts the server. The single quotes stop your shell from filling in the token, so the file stores the placeholder Step 4 shows rather than your secret.

By default the command uses local scope: the server is private to you and stored in ~/.claude.json under this project. Add --scope project to write it into the project’s .mcp.json instead, the shared file Step 4 shows. You can also edit .mcp.json directly; it is plain JSON.

💡Official docs are the source of truth

MCP add syntax evolves quickly. Rather than reproducing flags here, check claude mcp add --help and the Claude Code MCP docs for the current invocation.

Step 3: Inspect the connection

Inside a Claude Code session, /mcp lists every connected server and the tools it exposes:

SESSION Inspect the connection, then use it
  1. Typed in the terminal: claude --dangerously-skip-permissions
  2. You type in the session: /mcp
  3. The tool replies: Connected MCP servers: github (stdio) connected Tools: create_issue Create a new GitHub issue create_pull_request Open a pull request get_file_contents Read file contents from a repo list_issues List issues with optional filters search_repositories Search public repositories ... 18 more tools Resources: none Prompts: none
  4. You type in the session: Summarize the open issues labeled 'bug' in this repo and group them by severity label
  5. The tool did:github: list_issues (state open, label bug)
  6. The tool replies: Found 7 open bug issues: Critical (2): #84 — Auth token refresh fails on token expiry #91 — File upload silently drops files over 10 MB High (3): #77 — Search returns stale results after index rebuild #88 — Rate limiter counts OPTIONS requests #93 — Pagination cursor invalid after filter change Medium (2): #79 — Tooltip z-index overlaps modal header #86 — CSV export omits last row if row count is divisible by 100 Recommendation: #84 and #91 are blocking for a release — they affect data integrity and auth.

Illustrative session; the server list, issues and wording are examples, and your tool's screens will differ.

Notice what happened: no copy-pasting, no browser tab-switching. The agent called the MCP tool, got structured data, and reasoned over it. That’s the leverage.

Step 4: Project-scoped config

When you register a server with --scope project, Claude Code writes it to .mcp.json in your project root. Commit that file and your whole team gets the same server configuration. Claude Code asks each person to approve a project server before it first runs.

{
"mcpServers": {
"github": {
"command": "docker",
"args": ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
}
}
}
}

The ${GITHUB_PERSONAL_ACCESS_TOKEN} placeholder is resolved from the environment at runtime. The token never lives in the file; committing secrets into .mcp.json is a critical mistake to avoid (more on this below).

ℹAgent config is shared infrastructure

Treating .mcp.json as a team artifact — versioned, reviewed, documented — is the same discipline as treating your CI config or Dockerfile that way. When you add a new server, open a PR for it. Your teammates deserve to know what their agents can now reach.

Cross-tool parity

MCP support is nearly universal across the major CLI tools. The in-session command and config file location differ:

ToolConfig fileIn-session command
Claude Code.mcp.json (shared, --scope project); default local scope and --scope user are stored in ~/.claude.json/mcp
Copilot CLI~/.copilot/mcp-config.json (user) or .mcp.json / .github/mcp.json (workspace), via copilot mcp add or /mcp add in-session; the GitHub MCP server is built in/mcp
Antigravity (agy)/mcp manager, or agy mcp add → .agents/mcp_config.json (project) or ~/.gemini/config/mcp_config.json (user); remote servers use serverUrl/mcp
Codex CLIcodex mcp add <name> -- <command> → [mcp_servers.*] in ~/.codex/config.toml/mcp

Antigravity note: agy plugin import gemini migrates Gemini CLI MCP entries into Antigravity’s config. If you have existing remote server configs from Gemini CLI, the key url becomes serverUrl in Antigravity’s format.

The trust problem

Here is the reality that should make you pause: with tens of thousands of servers now listed in the registry, most have no formal vetting at all — no security review, no maintenance guarantee, no verified publisher. A clean README and a plausible name tell you nothing about whether the code was audited, who maintains it, or what it does with your credentials once it’s running.

The MCP spec’s security guidance says what a careful user always did: a client that offers one-click setup of a local server must show you the exact command it will execute, should flag anything that uses sudo, rm -rf, or reaches outside your project, and a local server should use stdio rather than an open network port. Read the command in your .mcp.json the same way.

An MCP server runs with real access to your agent and, through it, to your codebase and credentials. Connecting one is more like installing a dependency with shell access than adding a browser extension. Treat it accordingly.

Vetting checklist

Before connecting any third-party MCP server:

  • Who maintains it? Prefer official vendor servers (GitHub’s own server, Stripe’s own server, etc.) over community forks. Check whether the maintainer is reachable.
  • Is the repo active? Look at commit recency, open issues, and whether bugs get responses. An abandoned repo is a liability.
  • What scopes does it request? Read the server’s documentation and source. A server that needs admin:org when it only claims to “read issues” is a red flag.
  • Where do tokens live? Secrets must go in environment variables and be referenced via ${VAR_NAME} placeholders in config. Never hardcode tokens, API keys, or passwords into .mcp.json — that file gets committed.
  • Does it send data off-machine? Understand whether the server is local-only (stdio, processes files on your machine) or proxies requests through a third-party service. For sensitive codebases, local-only is strongly preferred.
⚠Secrets in .mcp.json

A hardcoded token in .mcp.json will end up in your git history. If the repo is ever public, that token is compromised. Use environment variables exclusively. Most secret-scanning tools (GitHub’s built-in scanner, gitleaks) will catch this in CI — but catching it before the push is better.

ℹInstitutional environments

Government and university machines often have policies governing what software can run, what external services can be reached, and what data can leave the network. Before connecting any MCP server on a managed machine, check with your IT or security team. A server that’s fine on a personal laptop may be out of policy on a classified or HIPAA-regulated workstation.

Enterprise roadmap

MCP’s Enterprise-Managed Authorization extension (stable since June 2026) lets your identity provider decide which MCP servers each person can reach, with SSO sign-in. Gateway proxies and registries of approved servers come from individual vendors. If you’re in an enterprise environment without these controls yet, treat manual vetting as your gate. Document which servers your team has approved and why.

KNOWLEDGE CHECK

You find a popular MCP server on GitHub with 800 stars. It promises to connect your agent to your company's internal database. What should you check before connecting it?

KNOWLEDGE CHECK

Your .mcp.json needs to pass a GitHub token to the GitHub MCP server. What's the correct approach?

KNOWLEDGE CHECK

What does an MCP server's 'stdio transport' mean in practice?


Key takeaways

  • MCP is vendor-neutral — donated to the Linux Foundation, supported across Claude Code, Copilot, Antigravity, Codex, Cursor, and ChatGPT
  • Three primitives: tools (actions), resources (data), prompts (templates) — a server exposes whichever it implements
  • stdio = local process, HTTP = remote service; local is preferable for sensitive work
  • .mcp.json is team infrastructure — commit it, review it, document what you’ve added and why
  • Most public servers are unvetted — vet before connecting, prefer official vendor servers
  • Secrets in env vars only — never hardcode tokens into .mcp.json
  • Institutional machines (gov, university) require a policy check before connecting any external server

Next: Skills and Hooks — teach your agent your team’s conventions once, and it follows them forever.

Search lessons