Skip to main content
Glama

MCP Server Engineering Lab

Lab 4 of 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

✅

2

RAG Engineering Lab

✅

3

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

Related MCP server: mcp-ikaos-story

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

python -m venv .venv
.venv/bin/pip install -r requirements-dev.txt      # Windows: .venv\Scripts\pip
python examples/client.py
pytest
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 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:

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 ToolErrors 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

The data and search, with no MCP code in it

kestrel_mcp/server.py

Tools, resources, prompt, scope checks

kestrel_mcp/auth.py

Token verifier and resource-server settings

kestrel_mcp/contract.py

Contract snapshot and breaking-change rules

examples/

Client config and a Python client

tests/

In-memory, stdio and HTTP tests

Articles

How to test this

The MCP Testing Lab in the AI Quality Engineering series goes further: fuzzing tool inputs, malicious servers and tool poisoning.

Licence and citation

Code: MIT. Articles: CC BY 4.0. Cite with CITATION.cff. Kestrel Labs is fictional.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      Read-oriented MCP server for Taranis AI, exposing the list_stories tool over stdio or Streamable HTTP for desktop AI assistants and developer tools.
      1
      -
    • F
      license
      A
      quality
      C
      maintenance
      Enables creating and modifying iKAOS Story prototype content, including reading context, saving content with optimistic revision control, and managing images, through a stdio MCP server that talks to the authenticated iKAOS Story API.
      7
      -
    • A
      license
      B
      quality
      B
      maintenance
      Enables MCP clients such as Claude and Cursor to read timelines, search statuses, and look up users or conversations, plus optionally post, delete, favorite, and follow with explicit confirmation. It supports both local stdio launches and remote HTTP hosting with per-user authorization.
      15
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables agents to perform federated cited search and heuristic grounding across a governed versioned wiki and indexed files, inspect citation spans, and read or write scoped knowledge through HTTP or stdio MCP.
      Apache 2.0