Back to search
mcp-server-engineering-lab
MCP serverGitHub
Lab 4 of the AI Engineering series: an MCP server with typed tools, resources, scoped bearer-token auth, a breaking-change contract gate and protocol-level tests.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/k11-software-solutions--mcp-server-engineering-lab)HTML
<a href="/listings/k11-software-solutions--mcp-server-engineering-lab"><img src="/api/listings/k11-software-solutions--mcp-server-engineering-lab/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 121 lines
- # 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.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.