Skip to content
Back to search

mcp-server-engineering-lab

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/k11-software-solutions--mcp-server-engineering-lab/badge.svg)](/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
  1. # MCP Server Engineering Lab
  2. **Lab 4 of [Becoming an AI Engineer](https://github.com/K11-Software-Solutions/becoming-an-ai-engineer).**
  3. Build an MCP server that any client can use, such as Claude Code, Cursor or an agent from lab 3.
  4. It exposes Kestrel's backlog and documents with typed tools, scoped permissions, bearer-token
  5. auth over HTTP, a contract gate that knows breaking changes from harmless ones, and tests that
  6. talk real MCP.
  7. ## The AI Engineering series
  8. | # | Lab | Status |
  9. |---|---|---|
  10. | 1 | [AI Engineering Foundations](https://github.com/K11-Software-Solutions/becoming-an-ai-engineer) | ✅ |
  11. | 2 | [RAG Engineering Lab](https://github.com/K11-Software-Solutions/rag-engineering-lab) | ✅ |
  12. | 3 | [Agent SDK Lab](https://github.com/K11-Software-Solutions/agent-sdk-lab) | ✅ |
  13. | 4 | **MCP Server Engineering Lab** (this repo) | ✅ |
  14. | 5 | AI Coding Assistant Extensions Lab | planned |
  15. | 6 | PDLC Agents Lab | planned |
  16. | 7 | Shipping Agents Lab | planned |
  17. | 8 | Agents on AWS Lab | planned |
  18. | 9 | Operating Agents Lab | planned |
  19. ## What the server offers
  20. | Kind | Name | Notes |
  21. |---|---|---|
  22. | Tool | `search_backlog(query, limit=3)` | read-only; structured results |
  23. | Tool | `get_story(story_id)` | read-only; flags text addressed to AI assistants in `warnings` |
  24. | Tool | `search_docs(query, limit=2)` | read-only; current documents only (superseded ADRs excluded) |
  25. | Tool | `create_story(title, description)` | needs `backlog:write`; idempotent by title |
  26. | Resource | `kestrel://stories/{story_id}` | one story as JSON |
  27. | Resource | `kestrel://docs/{doc_id}` | a whole document as Markdown; superseded ones say so |
  28. | Prompt | `triage_request(request)` | lab 1's triage task, phrased for this server's tools |
  29. Built on the official MCP Python SDK **2.3.0** (`MCPServer`, formerly `FastMCP` in 1.x).
  30. ## Run it
  31. ```bash
  32. python -m venv .venv
  33. ```
  34. ```bash
  35. .venv/bin/pip install -r requirements-dev.txt # Windows: .venv\Scripts\pip
  36. ```
  37. ```bash
  38. python examples/client.py
  39. ```
  40. ```bash
  41. pytest
  42. ```
  43. ```bash
  44. python -m kestrel_mcp.contract check
  45. ```
  46. ### Connect a client
  47. Over **stdio**, the client starts the server as a local process. For Claude Code, put
  48. [examples/mcp.json](examples/mcp.json) in your project as `.mcp.json`. Cursor reads the same
  49. format from `.cursor/mcp.json`. Writes stay off unless you set
  50. `KESTREL_MCP_SCOPES=backlog:read,backlog:write`.
  51. Over **Streamable HTTP**, each request needs a bearer token. Development tokens come from an
  52. environment variable. Generate your own tokens; never commit them:
  53. ```bash
  54. KESTREL_MCP_TOKENS="<token>=my-laptop:backlog:read" python -m kestrel_mcp --http --port 8000
  55. ```
  56. `StaticTokenVerifier` is for development only. In production, verify tokens from your identity
  57. provider; article 06 explains how.
  58. ## What the tests cover
  59. | Area | Examples |
  60. |---|---|
  61. | Discovery | tools, resources and prompt listed; annotations; output schemas; descriptions present |
  62. | Tools | structured results; superseded docs excluded; planted instruction flagged |
  63. | Errors | actionable `ToolError`s reach the model; invalid arguments rejected by schema; unexpected exceptions don't leak internals |
  64. | Permissions | writes off by default; read scope required; idempotent create |
  65. | Resources | JSON and Markdown; path traversal refused; missing document is an error |
  66. | HTTP auth | 401 with discovery header; bad, expired and wrong-audience tokens refused; reader vs writer scopes; DNS-rebinding host check; protected-resource metadata |
  67. | stdio | the server as a subprocess, read-only and with write scope |
  68. | Contract | server matches snapshot; six breaking changes caught; four compatible changes reported, not blocked |
  69. ## Layout
  70. | Path | What it shows |
  71. |---|---|
  72. | [kestrel_mcp/store.py](kestrel_mcp/store.py) | The data and search, with no MCP code in it |
  73. | [kestrel_mcp/server.py](kestrel_mcp/server.py) | Tools, resources, prompt, scope checks |
  74. | [kestrel_mcp/auth.py](kestrel_mcp/auth.py) | Token verifier and resource-server settings |
  75. | [kestrel_mcp/contract.py](kestrel_mcp/contract.py) | Contract snapshot and breaking-change rules |
  76. | [examples/](examples) | Client config and a Python client |
  77. | [tests/](tests) | In-memory, stdio and HTTP tests |
  78. ## Articles
  79. | # | Article |
  80. |---|---|
  81. | 01 | [What MCP Is For](articles/01-what-mcp-is-for.md) |
  82. | 02 | [Tools, Resources and Prompts](articles/02-tools-resources-and-prompts.md) |
  83. | 03 | [Designing Tools for a Model](articles/03-designing-tools-for-a-model.md) |
  84. | 04 | [Errors and Validation](articles/04-errors-and-validation.md) |
  85. | 05 | [Transports: stdio and Streamable HTTP](articles/05-transports.md) |
  86. | 06 | [Auth: Tokens, Scopes and Local Trust](articles/06-auth-tokens-and-scopes.md) |
  87. | 07 | [Testing an MCP Server, and Its Contract](articles/07-testing-and-contracts.md) |
  88. | 08 | [Untrusted Content, Clients and What Comes Next](articles/08-untrusted-content-and-next.md) |
  89. ## How to test this
  90. The [MCP Testing Lab](https://github.com/K11-Software-Solutions/mcp-testing-lab) in the AI Quality
  91. Engineering series goes further: fuzzing tool inputs, malicious servers and tool poisoning.
  92. ## Licence and citation
  93. Code: [MIT](LICENSE). Articles: [CC BY 4.0](articles/LICENSE.md). Cite with [CITATION.cff](CITATION.cff).
  94. Kestrel Labs is fictional.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.