Glossary

130 terms from Agent Tools and MCP, in plain words, each with the chapter that teaches it.

Search the glossary

#

--allowedTools: A Claude Code flag listing the tools that may run without asking. In -p mode, any tool not listed is refused instead of prompted.
-p (print mode): A Claude Code flag that runs one prompt without the interactive screen and prints the answer. Tools without an allow rule are refused rather than asked about.
.mcp.json: A project-folder file holding project-scoped MCP servers shared through version control. Each person approves them the first time.
_meta: A field in each request's `params` carrying the protocol version and client capabilities. Without a handshake, this is how every request stays self-contained.

A

Access token: A short-lived credential that a client sends as `Authorization: Bearer …` to prove who the person is and what they may do.
Additive write: A write tool whose repeat just adds a duplicate, like Kettle & Crane's open_ticket. It is usually acceptable because duplicates are easy to clean up.
Allowlist: A list of the only tools permitted, with everything else off; a denylist works the other way and turns off only named tools. The MCP connector's mcp_toolset uses them instead of per-call approval.
Annotated: A Python typing feature that attaches extra information, such as a Pydantic Field with a description and limits, to a type hint.
anyio: A package installed with mcp that includes a pytest plugin for running async test functions.
API key: A long secret that identifies a calling program, such as Priya's agent or a script. It is simple and suits programs better than signed-in people.
Approval gate: Host code that pauses a write tool call until a person or policy approves it; a refused call returns a 'held, don't retry' message to the model. Only the host can guarantee a person approved an action.
ASGI: The Python standard for asynchronous web apps, which FastAPI follows. `streamable_http_app()` returns the MCP server as an ASGI app you can mount.
async / await: Python keywords for code that waits for slow things (like a network reply) without blocking. `asyncio.run()` starts an async function and waits for its result.
Audience: The server a token was issued for. An MCP server must accept only tokens meant for it and never forward a client's token to another service.
Authorization server: In OAuth, the login provider (such as Okta or Auth0) that signs people in and issues tokens. It is separate from your MCP server.

B

base64: A way of writing bytes as letters, digits and a few symbols. list_orders uses it to encode its cursor.
BeforeValidator: A Pydantic hook that runs a function on a value before other checks. Kettle & Crane's clean_id uses it so " kc-20517 " becomes "KC-20517".
BEGIN IMMEDIATE: A SQLite command that locks the database for writing before any checks. It stops two simultaneous refund calls from both passing the limit check.

C

Capabilities: The optional features a client or server declares it supports, such as a server's tools, resources and prompts or a client's elicitation.
Claims check: A desk-agent test that flags a reply saying a request was handed on when no ticket was opened and nothing was held.
Claude Code: Anthropic's coding agent for the terminal, which acts as an MCP host. Jo uses it to check stock levels from the shop server.
Claude Desktop: Anthropic's desktop app, which is an MCP host. It starts local servers from claude_desktop_config.json and asks before each tool call.
claude mcp add: Claude Code commands for registering, listing, inspecting and removing MCP servers. Everything after `--` in `add` is the command that starts the server.
claude_desktop_config.json: The JSON file where Claude Desktop reads the local servers to start. It needs absolute paths because Desktop doesn't start in your project folder.
Client (MCP): The part of a host that talks to one server; a host has one client per server. Claude Code's connection to kc-shop is a client.
Client (SDK class): The Python SDK's class for connecting to a server over stdio, HTTP or in memory. It offers one async method per MCP request and replaces the old `initialize()` setup.
Client ID Metadata Document: A URL describing an OAuth client, the preferred way for MCP clients to identify themselves. It replaces the deprecated Dynamic Client Registration.
Confirm code: A short code returned with a preview of a destructive action, which must be sent back to proceed. In cancel_order it is a hash of a secret, the order ID and its status, so it stops working if the order changes.
Connectors (Claude): Remote MCP servers added in claude.ai, which Claude Code can also pick up. Don't confuse them with the API's MCP connector.
Content blocks: The pieces of a tool result's `content` list: text, image, audio, resource links or embedded resources.
Contract tests: Tests that fail when what clients and models see, such as tool definitions, changes. Kettle & Crane's compare each tool's fingerprint to a reviewed snapshot.
curl: A command-line tool for sending HTTP requests, used to send raw MCP requests to the HTTP server.
Cursor: An opaque token a caller passes back to get the next page of results. list_orders returns one when more orders remain.

D

Destructive write: A write tool whose effect can't be undone, like cancel_order. It needs confirmation and limits enforced in code.
Dispatch table: A lookup table in an agent host that maps each tool name offered to the model to the actual tool that runs it. The host's `execute` function runs only names in the table, so the model can't call a tool that wasn't offered or skip a gate by altering a name.
DNS rebinding: A trick that lets a web page make the browser treat a server on your own computer as the page's own site. Checking the `Origin` and `Host` headers blocks it.
Dual-era: Speaking both the older handshake-based protocol revisions and the stateless 2026-07-28 one. The Python SDK's client tries `server/discover` first and falls back to `initialize`.

E

Elicitation: A server asking the person for input mid-call, through the host and with a small form. Host support varies.
Errors as data: Returning a failure as readable text marked as an error, not crashing, so the model can act on it and correct itself.
Eval (tool-use evaluation): A test that grades whole agent runs: did it call the tools it must, avoid the ones it mustn't, and state the key fact. Evals cost money, so they run when descriptions, tools or models change.

F

FastAPI: A Python web framework (from an earlier book). The shop's MCP server is mounted inside a FastAPI app to add a health check and API-key checks.
FastMCP: The server class name in version 1 of the Python MCP SDK; SDK 2 renamed it MCPServer. Many tutorials still use it.
Field: A Pydantic function for adding descriptions and limits (pattern, ge, le, max_length) to a type. Those become schema keywords the model reads and Pydantic enforces.
Fingerprint: A short hash of everything the model reads about a tool (name, description, schema, annotations). It is used to detect changes.
Fixture: A function pytest runs for you to prepare a test. With `autouse=True`, `fresh_shop` resets the shop before every test.

H

Hash: A fixed-length fingerprint computed from some data. It is used for cache file names, confirm codes and tool fingerprints.
Host: The AI application the person uses, which runs the model, holds one client per server and decides which tools run. Claude Desktop and Priya's agent are hosts.
Host addresses (127.0.0.1, 0.0.0.0): 127.0.0.1 (localhost) is reachable only from this computer; 0.0.0.0 listens on every network interface. Bind local servers to 127.0.0.1, never 0.0.0.0.
HTTP status codes: Numbers an HTTP server returns: 400 header mismatch, 401 missing or wrong key or token, 403 forbidden (bad Origin or missing scope), 404 not found, 421 wrong host, 500 server error.
httpx2: The HTTP client the MCP SDK uses, with an interface like httpx. You pass one carrying an Authorization header to `Client` for authenticated HTTP.

I

Idempotency key: A unique ID the caller makes up to name one intended action, such as a refund. Sending the same ID on a retry makes the server do the work at most once.
Idempotent: A call that has no extra effect when repeated. issue_refund is idempotent because retrying with the same request ID never pays twice.
In memory (client): Connected to a server object in the same process, with no subprocess or transport. It runs the same requests and validation, so it makes fast pytest tests.
initialize: The opening request of older MCP revisions that set up a session. The 2026-07-28 revision dropped this handshake.
instructions (server): A short text a server supplies in `server/discover` that a host may add to the model's context as advice for all its tools.
isError: The flag in a tool result showing the tool ran and failed. The Python SDK exposes it as `is_error`.

J

JSON Schema: A JSON description of what valid data looks like. The model reads it to fill in tool arguments, and Pydantic builds it from type hints.
JSON-RPC 2.0: A small standard for calling functions with JSON. MCP messages are JSON-RPC requests, responses and notifications.
JWT: A signed token, covered in the FastAPI book. A real token verifier checks its signature, issuer, expiry and audience.

L

Least privilege: Giving each server and agent only the tools, data and credentials its job needs. Sam's sign-in, for example, reaches a server that can't refund at all.
Lifespan: FastAPI code that runs when an app starts and stops. A mounted MCP app needs it to start the MCP request handler (`mcp.session_manager.run()`).
Literal: A Python type that allows only the listed values, such as the order Status. It appears as an enum in the schema.
Load balancer: A front server that spreads requests across several copies of a server. A stateless MCP server can run behind one.
Lock file: A saved list of reviewed versions or hashes, checked before use. weather.lock.json holds the tool hashes approved for the weather server.

M

MCP connector: A Claude API beta where Anthropic's servers act as the MCP client: you list remote servers in the request and they fetch tools and run calls in one API call. It works only with public HTTPS servers and supports allow and deny lists, not per-call approval.
MCP Inspector: The official tool, run with npx, for exploring and testing MCP servers in a browser or with `--cli`. It lists and calls tools, resources and prompts.
MCP request headers: HTTP headers that repeat key parts of an MCP message so proxies can route without reading the body. A header that disagrees with the body gets HTTP 400 and code -32020.
mcp__<server>__<tool>: How Claude Code names MCP tools in permission rules, such as `mcp__kc-shop__check_stock`.
MCPServer: The high-level server class in SDK 2 (`mcp` 2.x), where you register tools, resources and prompts and call `run()`. It was named FastMCP in SDK 1.
Middleware: Code in a web app that runs on every request before the route handler. The shop's require_api_key middleware checks the key on /mcp.
MIME type: A standard label for a kind of content, such as text/markdown or image/png. A resource declares one.
Model Context Protocol (MCP): An open standard for connecting AI applications to tools and data. You write tools once in a server and any MCP-speaking app can use them.
Multi round-trip request: A request where the server answers with `resultType: "input_required"` and the client repeats the request with the answers. It is how elicitation works.

N

Namespacing (tool prefix): Adding a per-server prefix such as `shop__` to tool names so one server's tool can't shadow another's.
Notification: A JSON-RPC message with no `id`, so no reply is expected.
npx: A Node.js tool that downloads and runs a package in one step; `uvx` does the same for Python tools. Both are used to run servers and the Inspector, and you should pin an exact version.

O

OAuth 2.1: The sign-in and token standard MCP uses for HTTP servers. The person signs in through a browser and the host gets a short-lived access token.
Observability (tracing): Recording each tool call's name, arguments, time and size so you can debug an agent. `traced` writes one JSON line per call.
Opaque: Meant to be passed back without being read, as with a cursor, so its contents can change later. Callers can still edit it, so the server validates it.
OpenTelemetry: A tracing standard. The SDK records its spans by default, and MCP's `_meta` can carry a trace ID.
Origin header: An HTTP header browsers send naming the page's site. Servers check it, along with `Host`, to refuse requests from other websites.
Output schema: A JSON Schema for a tool's structured result, built from a return type like a Pydantic model.

P

Parallel calls: Several `tool_use` blocks in one model step, which cut round trips. They show as repeated step numbers in the output.
Pinning: Fixing exact versions of packages and hashes of tool definitions so changes can't arrive unnoticed. You upgrade only on purpose, after review.
PKCE: A one-time secret used in the OAuth sign-in so a stolen sign-in code is useless.
Prompt (MCP): A message template a server offers that the person picks, often from a menu. Kettle & Crane's reply_to_customer is one.
Prompt caching: Reusing an identical start of a request, such as tool definitions, at a lower input price. It needs the tool list in the same order every time.
Prompt injection: Instructions hidden in text the model reads, such as an email or tool result, that try to make it misbehave. Rory's gift note on KC-73005 is an example.
Protected resource metadata: A JSON document naming the authorization server and scopes a server uses. A 401 response's `WWW-Authenticate` header points clients to it.
Protocol error: A JSON-RPC `error` with a code, meaning the request itself was wrong (bad params, unknown method, unsupported version). Models rarely can fix these.
Protocol revision: A dated version of the Model Context Protocol, such as 2026-07-28, which made the protocol stateless. Each request names the revision it speaks, so clients and servers can tell which rules apply.
Pydantic: A Python library that checks data against type hints. Here it builds a tool's JSON Schema and validates every call.
pytest: Python's test runner, used to test the server in memory.

R

Regular expression: A text-matching pattern. A `pattern` like `^KC-\d{5}$` restricts order IDs, and audit and claims checks use regexes too.
Resource: Addressed data a server offers for the app to read and show or add to context, like the help article kc://help/returns.
Resource Indicators: An OAuth feature where clients send the server's URL as `resource` in sign-in and token requests, so the token is issued for that server alone.
Resource server: In OAuth, the server that checks access tokens on every request. Your MCP server plays this role.
Resource template: A resource address with placeholders, such as `kc://help/{slug}`, whose matching part is passed to the function as an argument.
Rug pull: A server that behaves well while you evaluate it and changes its tools afterward.

S

Sampling and roots: Older MCP features: servers asking the client's model to write (sampling) and clients naming folders (roots). Both are deprecated in the 2026-07-28 revision.
Scope (Claude Code): Where a Claude Code server setting applies: local (you, this project), project (everyone who clones it, in .mcp.json) or user (you, everywhere).
Scope (OAuth): A named permission inside a token, such as `orders:read`. A request with a token lacking a required scope is refused.
SDK: Software development kit; here, the official `mcp` Python library, which includes both server and client code. SDK 2 (`mcp` 2.x) provides the `MCPServer` class and a `Client` object, replacing `FastMCP` from version 1.
Server (MCP): A program that offers tools, resources and prompts over MCP. It only answers its client and never talks to the model directly.
server/discover: The request in which a server reports its supported protocol versions, capabilities, instructions and identity. It replaces the old handshake.
SQLite: A database stored in one file, used through Python's built-in `sqlite3` module for the pretend shop (shop.db).
SSE stream: Server-Sent Events: several messages sent down one HTTP response, used when a server sends progress updates before the final result.
Stateless: Every request carries everything the server needs, so there's no handshake or session and any copy of the server can answer.
stdio: A transport where the host starts the server as a child process and talks through its standard input and output. A stdio server must never print to standard output.
Streamable HTTP: A transport where the server runs on its own and the client sends each message as an HTTP POST to one endpoint, such as /mcp. It suits shared and remote servers.
Structured content: A JSON value for programs to read, sent alongside a tool's text. It results when a tool returns a Pydantic model, TypedDict or similar.

T

Token verifier: Server code with a `verify_token` method that checks an access token and returns an `AccessToken`, or None to refuse it.
Tokens (LLM): The chunks of text a model reads and writes, roughly four characters each. Tool definitions and results cost tokens on every step.
Tool: A function a server offers that the model can ask to run, such as get_order or issue_refund. The model controls when tools are used.
Tool annotations: Hints sent with a tool's definition: read-only, destructive, idempotent and open-world. Hosts use them to decide when to ask, but they are only hints and untrusted servers can lie.
Tool error: A normal result with `isError: true`, meaning the tool ran and failed. The model sees it and can correct itself.
Tool poisoning: Prompt injection hidden in a tool's description. The model reads every description on every step, even for tools it never calls.
Tool runner: A built-in loop in the Anthropic SDK that calls the model and runs tools for you.
Tool search: Loading tool definitions only when the model needs them, which Claude Code does to save tokens.
ToolError: An exception from the `mcp` package. Raising it sends your message to the model as a tool error, while any other exception reaches the client only as a generic message.
Transaction: A group of database reads and writes that succeed or fail together. The refund tool does its checks and insert in one.
Transport: How messages travel between client and server. MCP defines stdio and Streamable HTTP, and the messages are the same either way.
ttlMs / cacheScope: Fields on list results saying how long (in milliseconds) and for whom a client may reuse them. Kettle & Crane's server gives `tools/list` five minutes.
TypeAdapter: A Pydantic class that wraps any type, including a function, to validate data or produce its JSON Schema. It powers `to_tool` and `call`.

U

URI: An address like `https://…` or `kc://help/returns`. Servers may invent their own schemes such as `kc://`.
UUID: A random 128-bit ID written like `7c3e9a51-2b84-…`, good for request IDs. Generate it once per action and reuse it on retries.
Uvicorn: The Python web server that runs ASGI apps such as the shop's HTTP server.

V

Virtual environment: An isolated folder of Python packages for a project. Claude Desktop's config must point at its Python so the `mcp` package is found.

W

WWW-Authenticate: The HTTP header on a 401 response that tells clients how to authenticate, and in MCP's OAuth flow where to find the protected resource metadata.

Z

Zero data retention: Anthropic's arrangement for not storing request data after processing. As of October 2026, MCP connector requests aren't eligible.