1. Getting started¶
What MCP is, in one page¶
The Model Context Protocol (MCP) connects an AI application (the host, such as Claude Desktop, VS Code or your own agent) to servers that offer it capabilities. A server offers three kinds of things:
- Tools: functions the model can call, such as
books.search. - Resources: data the host can show or attach, such as a file or a record.
- Prompts: reusable messages a user can pick.
When a session starts, the host asks the server for its tools and sends every definition (name, description, input schema and output schema) to the model as part of its context. When the model calls a tool, the result goes into the context too.
That is the whole problem this book is about. Everything a server sends is read by the model, on every turn, and paid for in tokens, time and attention. A server with 40 verbose tools can use 20,000 tokens before the user has typed a word. A search that returns 500 rows can push the conversation out of the context window. A write that times out and is retried can charge a card twice.
OunceMCP is a framework on top of FastMCP that makes the right thing the default: it measures every definition and result, shapes results to a budget, and gives writes and security first-class support.
Installing¶
You need Python 3.11 or newer and uv.
To follow the book with its code, clone the repository:
pipx install ouncemcp works too. To use the clone instead, run uv tool install -e ..
The commands you will use¶
| Command | What it does |
|---|---|
ouncemcp init NAME |
Scaffold a new server with tests and CI |
ouncemcp dev server.py |
Run with hot reload and a token count per call |
ouncemcp check server.py |
Measure every definition and run the lints |
ouncemcp context server.py TOOL |
Show exactly what the model receives |
ouncemcp eval suite.yaml |
Run a task suite with a model |
ouncemcp trace |
Open the trace and report viewer |
ouncemcp audit TARGET |
Measure any MCP server, even one not built with OunceMCP |
Appendix A lists every option.
A project of your own¶
If you want a fresh project rather than the book's code, init writes a working server, tests and a CI workflow:
The quickstart walks through that project and connecting it to a host.
Summary¶
- The host sends every tool definition and every result to the model. Size is cost.
- OunceMCP measures that cost and keeps it within budgets you set.
check,devandcontextare the tools you will reach for most.
Next, we write the first version of Shelf.