Module 04 · Building an MCP Server
Testing Your MCP Server Locally With Claude Code
Open lesson + course map
On this lesson
Course outline
Module 1 · Claude Code Fundamentals
Module 2 · CLI Workflows
Module 3 · Model Context Protocol Basics
Module 4 · Building an MCP Server
Test server logic without a model first, protocol behavior second, and Claude Code integration last. This makes failures reproducible and prevents a fluent model response from hiding a broken contract.
// concept
Build Three Test Layers
- Unit: schemas, authorization, lookup, redaction, errors.
- Protocol/integration: initialize, capability discovery, calls, resources, malformed messages, shutdown.
- Host acceptance: Claude Code discovers only intended capabilities and respects approval/tool boundaries.
Use synthetic fixtures and a temporary configuration scope. Capture versions and deterministic assertions. Do not make live payments, emails, or production writes during local tests.
// concept
Test Abuse Cases
Include oversized input, unknown field, traversal, prompt injection in resource content, cross-tenant ID, repeated call, timeout, process crash, malformed output, and secret-like fixture. Confirm logs use safe references.
For a draft write, repeat the same idempotency key and confirm one record. For read-only examples, prove the process has no write credential.
// worked_example
Worked Example
The sample catalog server passes 18 unit/protocol tests. In Claude Code, the tester asks for SKU PK-A14, an unknown SKU, and ../../.env. Only the valid product returns. Capability inspection shows no generic filesystem or network tool.
The tester places malicious instructions inside a product description. Claude may see the text, but no privileged tool exists and the system policy labels results as untrusted data.
// failure_cases
Failure Cases to Diagnose
6 cases to diagnose
Only manual chat test
add deterministic client tests.
Mocks omit real schema
test serialized protocol messages.
Production config reused
isolate identity and fixtures.
Expected failure prints stack
assert safe error shape.
Capability creep unnoticed
snapshot intended discovery.
Process remains after test
verify cleanup.
// concept
Operator Note
Keep model-dependent acceptance tests separate from deterministic protocol tests. Model behavior and provider versions can change, so record the tested model/date and assert safety properties at the host/tool boundary regardless of wording. A test passes because the forbidden effect is impossible or rejected, not because one model happened to decline it in a sample conversation.
// pakistan_angle
Pakistan Angle
Use fake CNIC-like values clearly marked invalid, non-routable example contacts, and synthetic PKR orders. Never upload a real customer export to “see if it works.”
Test Windows/WSL process and path behavior if that is the delivery environment. Record exact commands a Pakistani client team can rerun without your account.
// hands_on
Hands-On Exercise
5 steps
Write unit, protocol, and host tests.
Add ten abuse/failure cases.
Use temporary Claude Code configuration.
Snapshot discovered capabilities.
verify cleanup and reproducibility.
// completion_rubric
Completion Rubric
6 checks — tick as you verify
// sources
Sources
3 official sources — check every claim yourself
// check_yourself
Check yourself
4 questions · answers and options are taken word-for-word from this course
1 / 4 · diagnose
Your work shows this failure mode: “Only manual chat test.” What does the lesson tell you to do about it?