Kestrel MCP Server
README.md
# MCP Server Engineering Lab
**Lab 4 of [Becoming an AI Engineer](https://github.com/K11-Software-Solutions/becoming-an-ai-engineer).**
Build an MCP server that any client can use, such as Claude Code, Cursor or an agent from lab 3.
It exposes Kestrel's backlog and documents with typed tools, scoped permissions, bearer-token
auth over HTTP, a contract gate that knows breaking changes from harmless ones, and tests that
talk real MCP.
## The AI Engineering series
| # | Lab | Status |
|---|---|---|
| 1 | [AI Engineering Foundations](https://github.com/K11-Software-Solutions/becoming-an-ai-engineer) | ✅ |
| 2 | [RAG Engineering Lab](https://github.com/K11-Software-Solutions/rag-engineering-lab) | ✅ |
| 3 | [Agent SDK Lab](https://github.com/K11-Software-Solutions/agent-sdk-lab) | ✅ |
| 4 | **MCP Server Engineering Lab** (this repo) | ✅ |
| 5 | AI Coding Assistant Extensions Lab | planned |
| 6 | PDLC Agents Lab | planned |
| 7 | Shipping Agents Lab | planned |
| 8 | Agents on AWS Lab | planned |
| 9 | Operating Agents Lab | planned |
## What the server offers
| Kind | Name | Notes |
|---|---|---|
| Tool | `search_backlog(query, limit=3)` | read-only; structured results |
| Tool | `get_story(story_id)` | read-only; flags text addressed to AI assistants in `warnings` |
| Tool | `search_docs(query, limit=2)` | read-only; current documents only (superseded ADRs excluded) |
| Tool | `create_story(title, description)` | needs `backlog:write`; idempotent by title |
| Resource | `kestrel://stories/{story_id}` | one story as JSON |
| Resource | `kestrel://docs/{doc_id}` | a whole document as Markdown; superseded ones say so |
| Prompt | `triage_request(request)` | lab 1's triage task, phrased for this server's tools |
Built on the official MCP Python SDK **2.3.0** (`MCPServer`, formerly `FastMCP` in 1.x).
## Run it
```bash
python -m venv .venv
```
```bash
.venv/bin/pip install -r requirements-dev.txt # Windows: .venv\Scripts\pip
```
```bash
python examples/client.py
```
```bash
pytest
```
```bash
python -m kestrel_mcp.contract check
```
### Connect a client
Over **stdio**, the client starts the server as a local process. For Claude Code, put
[examples/mcp.json](examples/mcp.json) in your project as `.mcp.json`. Cursor reads the same
format from `.cursor/mcp.json`. Writes stay off unless you set
`KESTREL_MCP_SCOPES=backlog:read,backlog:write`.
Over **Streamable HTTP**, each request needs a bearer token. Development tokens come from an
environment variable. Generate your own tokens; never commit them:
```bash
KESTREL_MCP_TOKENS="<token>=my-laptop:backlog:read" python -m kestrel_mcp --http --port 8000
```
`StaticTokenVerifier` is for development only. In production, verify tokens from your identity
provider; article 06 explains how.
## What the tests cover
| Area | Examples |
|---|---|
| Discovery | tools, resources and prompt listed; annotations; output schemas; descriptions present |
| Tools | structured results; superseded docs excluded; planted instruction flagged |
| Errors | actionable `ToolError`s reach the model; invalid arguments rejected by schema; unexpected exceptions don't leak internals |
| Permissions | writes off by default; read scope required; idempotent create |
| Resources | JSON and Markdown; path traversal refused; missing document is an error |
| HTTP auth | 401 with discovery header; bad, expired and wrong-audience tokens refused; reader vs writer scopes; DNS-rebinding host check; protected-resource metadata |
| stdio | the server as a subprocess, read-only and with write scope |
| Contract | server matches snapshot; six breaking changes caught; four compatible changes reported, not blocked |
## Layout
| Path | What it shows |
|---|---|
| [kestrel_mcp/store.py](kestrel_mcp/store.py) | The data and search, with no MCP code in it |
| [kestrel_mcp/server.py](kestrel_mcp/server.py) | Tools, resources, prompt, scope checks |
| [kestrel_mcp/auth.py](kestrel_mcp/auth.py) | Token verifier and resource-server settings |
| [kestrel_mcp/contract.py](kestrel_mcp/contract.py) | Contract snapshot and breaking-change rules |
| [examples/](examples) | Client config and a Python client |
| [tests/](tests) | In-memory, stdio and HTTP tests |
## Articles
| # | Article |
|---|---|
| 01 | [What MCP Is For](articles/01-what-mcp-is-for.md) |
| 02 | [Tools, Resources and Prompts](articles/02-tools-resources-and-prompts.md) |
| 03 | [Designing Tools for a Model](articles/03-designing-tools-for-a-model.md) |
| 04 | [Errors and Validation](articles/04-errors-and-validation.md) |
| 05 | [Transports: stdio and Streamable HTTP](articles/05-transports.md) |
| 06 | [Auth: Tokens, Scopes and Local Trust](articles/06-auth-tokens-and-scopes.md) |
| 07 | [Testing an MCP Server, and Its Contract](articles/07-testing-and-contracts.md) |
| 08 | [Untrusted Content, Clients and What Comes Next](articles/08-untrusted-content-and-next.md) |
## How to test this
The [MCP Testing Lab](https://github.com/K11-Software-Solutions/mcp-testing-lab) in the AI Quality
Engineering series goes further: fuzzing tool inputs, malicious servers and tool poisoning.
## Licence and citation
Code: [MIT](LICENSE). Articles: [CC BY 4.0](articles/LICENSE.md). Cite with [CITATION.cff](CITATION.cff).
Kestrel Labs is fictional.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues