Skip to content

10. Testing

A server is used by a model that will try every argument you did not expect. Tests are how you find out first. Every stage of Shelf is tested in tests/test_book_shelf.py; this chapter walks through the patterns.

Calling tools in-process

await server.call_tool(name, arguments) runs a tool exactly as a client would, with shaping, policies and errors, but without a network:

result = await server.call_tool("books.search", {"query": "ada"})
assert result.structured_content["total"] > 0
assert result.meta["ouncemcp"]["result_tokens"] < 500

Use pytest with anyio (or pytest-asyncio) for async tests. Errors are results, not exceptions: check result.is_error and result.meta["ouncemcp"]["error"].

Writes: approvals and retries

A fresh server per test, and an approver that answers for the person:

tests/test_book_shelf.py
@pytest.mark.anyio
async def test_step3_borrowing_needs_a_yes_and_happens_once():
    step = module("step3_writes")
    declined = step.build(approver=lambda request: False)
    assert (
        error_code(await call(declined, "loans.borrow", {"book_id": "b-001"}))
        == "approval_declined"
    )
    assert declined.deps.writes == []

    library = step.Library()
    server = step.build(library, approver=lambda request: True)
    loan = (await call(server, "loans.borrow", {"book_id": "b-002"})).structured_content
    again = (await call(server, "loans.borrow", {"book_id": "b-002"})).structured_content
    assert loan == again and library.writes == ["borrow b-002 by demo-member"]  # replayed
    mine = (await call(server, "loans.mine")).structured_content["loans"]
    assert [l["loan_id"] for l in mine] == [loan["loan_id"]]
    returned = (await call(server, "loans.return", {"loan_id": loan["loan_id"]})).structured_content
    assert returned["returned"] and library.writes[-1] == f"return {loan['loan_id']}"

This one test checks the four things chapter 6 promised: a declined borrow changes nothing, an approved borrow happens, a repeated borrow is replayed rather than repeated, and returning works.

To test the question the person actually sees, connect a real FastMCP Client with an elicitation_handler and record the message; the book's tests check the exact preview text.

Callers and isolation

as_caller sets the verified identity for the code inside it, as if a token had been verified:

tests/test_book_shelf.py
@pytest.mark.anyio
async def test_step4_members_see_only_their_branch_and_loans():
    step = module("step4_secure")
    server = step.build(approver=lambda request: True)
    north_book = next(b.id for b in server.deps.books.values() if b.branch == "north")
    with as_caller(**ANA):
        loan = (await call(server, "loans.borrow", {"book_id": north_book})).structured_content
        assert error_code(await call(server, "loans.open")) == "unknown_tool"  # hidden from members
    with as_caller(**BO):
        assert error_code(await call(server, "books.get", {"id": north_book})) == "not_found"
        assert (
            error_code(await call(server, "loans.return", {"loan_id": loan["loan_id"]}))
            == "not_found"
        )
    with as_caller(**LIBRARIAN):
        open_loans = (await call(server, "loans.open")).structured_content["loans"]
    assert [l["loan_id"] for l in open_loans] == [loan["loan_id"]]
    assert server.deps.writes == [f"borrow {north_book} by ana"]

Write the intruder test for every tenant boundary: one tenant creates something, another tries to read, change or list it.

The security catalog

ouncemcp.eval.run_security_suite runs standard attacks against your server. It always probes guessed names for every tool with a policy, and runs the cases you add: cross-tenant reads, cursor and handle reuse, SSRF probes for URL arguments, and token passthrough.

tests/test_book_shelf.py
@pytest.mark.anyio
async def test_step5_passes_the_security_catalog():
    from ouncemcp.eval import CrossTenant, CursorReuse, run_security_suite

    server = module("step5_complete").build(approver=lambda request: True)
    report = await run_security_suite(
        server,
        [
            CrossTenant("books.get", {"id": "b-002"}, owner=ANA, intruder=BO),
            CursorReuse("books.search", {"query": "the", "limit": 1}, owner=ANA, intruder=BO),
        ],
    )
    assert report.passed, report.render_text()

Keeping definitions honest

Two more tests are worth having in every project:

from ouncemcp.cli import main
from ouncemcp.core.lints import lint_server

def test_check_passes():
    assert main(["check", "server.py"]) == 0
    assert lint_server(server) == []

Pin token counts too, if you care about them. await server.cost_report() measures the tools the current caller can see (for Shelf without a token, 1,109 tokens: the two librarian tools are hidden), and a test that fails when a definition grows makes the cost visible in review:

cost = await server.cost_report()
assert cost.total <= 1_200
assert {t.name: t.total for t in cost.tools}["books.search"] <= 250

Protocol conformance

OunceMCP itself is checked against the official MCP conformance suite in CI (ouncemcp.eval.conformance is the target server it runs against), so your server inherits a protocol layer that is known to conform. To test your own transport setup end to end, connect a FastMCP Client to the running server over HTTP or stdio in a test; see the testing guide.

Summary

  • server.call_tool runs a tool in-process with everything but the network.
  • Build a fresh server per test; answer approvals with approver=.
  • as_caller signs in as anyone; test every tenant boundary from both sides.
  • Run the security catalog and check in your test suite.