Module 7: Testing, Debugging, and Integration

Capsule description

You have functional MCP servers. In modules 4 and 5 you built servers in TypeScript and Python. In module 6, you created MCP Apps with visual output. Everything "works in your terminal." But there's an uncomfortable question you've probably been avoiding: does it really work?

"It works on my machine" is the epitaph of projects that die in production. An MCP server that returns the correct result with your test data, with your version of Node, on your laptop, isn't a reliable MCP server — it's a prototype with luck. The moment someone else uses it, or you use it a month later, or Claude Code invokes it with inputs you didn't anticipate, the bugs you didn't test, the errors you didn't log, and the configurations you assumed without verifying all appear.

This module closes that gap. You go from "it works" to "it works reliably."

Phase 3 of this guide is called Production for a reason. It's not "production" in the sense of deploying to a cloud server — it's production in the sense that your MCP server is robust enough to trust. So that Claude Code uses it in real flows without you worrying that it will fail silently, return incorrect data, or lose the connection without you noticing.

Where are we?

Context within the guide

Phase 1: MCP Fundamentals (Modules 1-3)
  ✅ Module 1: What MCP is and why it matters
  ✅ Module 2: Host-Client-Server Architecture
  ✅ Module 3: Three Primitives — Resources, Tools, Prompts

Phase 2: Build MCP Servers (Modules 4-6)
  ✅ Module 4: MCP Server in TypeScript
  ✅ Module 5: MCP Server in Python
  ✅ Module 6: MCP Apps and Interactive UI

Phase 3: Production (Modules 7-8)
  → Module 7: Testing, Debugging, and Integration (YOU ARE HERE)
  ○ Module 8: Project — Real MCP Server

What you already know

From the previous modules you bring:

The complete MCP mental model — Host-Client-Server architecture, protocol, data flow
The 3 primitives — Resources, Tools, Prompts implemented in two languages
Functional MCP servers — TypeScript with Zod, Python with decorators and Pydantic
MCP Apps — servers that return interactive UI
Experience with MCP Inspector — you used it to test your servers manually
Experience with Claude Code — you connected servers and verified that Claude Code uses them

What's missing

Your servers work, but you have no way to automatically test that they keep working after a change. You have no logging to tell you what happened when something fails. You don't have a systematic process to diagnose problems with the Claude Code connection. And you don't have a reference guide for the most common errors you'll encounter in production.

This module gives you all of that.

Why testing isn't bureaucracy

There's a natural resistance to testing, especially in personal or learning projects. "I already tested that it works, why do I need a test?" The answer is a scenario you've probably already lived:

The silent bug scenario

Imagine your MCP server has a search_files tool that searches for files by name. You tested it: it works. Two weeks later, you update a dependency. Everything compiles. You open Claude Code, ask it to search for a file, and Claude tells you "No files found" — but the file exists. What happened?

Without tests: you spend 30 minutes debugging. You review the code. You review the configuration. You add console.log everywhere. Eventually you discover that the new version of the dependency changed the output format, and your parser expects the previous format.

With tests: you run npm test. One test fails: "search_files: expected results.length to be > 0, received 0". You know exactly which tool is broken, what was expected, and what you received. The fix takes 5 minutes.

That's the investment. 10 minutes writing a test save you 30 minutes of debugging. Multiplied by every change you make in the server's life, the tests pay for themselves many times over.

The Claude Code in production scenario

There's a worse scenario: your MCP server works when you test it manually, but fails in subtle ways when Claude Code uses it:

Claude sends a string where you expected a number
Claude omits a parameter you thought was required
Claude sends Unicode characters your parser doesn't handle
Claude invokes the tool twice simultaneously and your code isn't thread-safe

These bugs don't appear in manual tests because you always send "reasonable" data. Claude Code doesn't have that bias. An automated test that simulates edge-case inputs detects these problems before Claude Code finds them.

Testing as a safety net, not a chore

The right mindset isn't "I have to write tests" but "I want a safety net." Each test is a guarantee: "this works." When you modify your server — add a tool, change a schema, update a dependency — you run the tests and know in seconds whether you broke something.

It's the difference between walking a tightrope with a net and without a net. The rope is the same, but your confidence (and your speed) are completely different.

The math of testing in MCP

To make it concrete, think about the numbers:

A typical MCP server has:
├── 4-6 tools
├── 2-3 resources
├── 2-3 prompts
└── Error handling in each one

Without tests:
├── Change in the code → Does it work?
├── Manual test of each tool → 2-3 min each
├── Manual test of each resource → 1-2 min each
├── Total per change: 15-25 minutes of manual testing
├── Changes per week: 5-10
└── Total per week: 1-4 hours of manual testing

With tests:
├── Change in the code → npm test
├── 15-20 tests run → 3-5 seconds
├── Result: ✅ everything passes or ❌ a specific test fails
├── Total per change: 5 seconds
├── Initial cost: 30-45 minutes writing the test suite
└── ROI: pays off in the first week

And that's without counting the bugs the tests detect and the manual tests don't. The return on investment is clear.

What kind of tests an MCP server needs

Not all tests are equal. An MCP server needs specific tests for its nature as a protocol server:

Type of test	What it verifies	Example
Tool unit test	That the tool returns the correct result	`search_files("*.ts")` returns .ts files
Resource unit test	That the resource exposes the correct data	`project://status` returns valid JSON
Validation test	That invalid inputs are rejected	A string where a number is expected → descriptive error
Error handling test	That errors are handled without crashing	A nonexistent file → `isError: true`, not an exception
Integration test	That the server responds to the protocol	`tools/list` returns all the registered tools

In capsule 02, you implement each of these types.

The three layers of this module

This module covers three layers that work together:

1. Testing (Capsule 02)

Writing automated tests for your MCP servers:

Testing MCP servers:
├── Unit tests for individual tools
│   ├── Does the tool return the correct result?
│   ├── Does the tool handle invalid inputs?
│   └── Does the tool handle errors from the external service?
├── Unit tests for resources
│   ├── Does the resource return the expected data?
│   └── Does the resource handle nonexistent URIs?
├── Integration tests
│   ├── Does the server initialize correctly?
│   ├── Are the capabilities announced correctly?
│   └── Does the request → response flow work end-to-end?
└── Error handling tests
    ├── Are errors returned with isError: true?
    ├── Are the error messages descriptive?
    └── Does the server recover from errors without crashing?

2. Debugging (Capsule 03)

Tools and techniques for when something doesn't work:

Debugging MCP servers:
├── MCP Inspector
│   ├── Interactive testing of tools and resources
│   ├── Inspection of requests and responses
│   └── Verification of capabilities
├── Logging
│   ├── What to log (requests, errors, timing)
│   ├── How to log (without breaking the stdio protocol)
│   └── Logging levels
└── Tracing
    ├── Follow a request through the server
    ├── Measure response times
    └── Identify bottlenecks

3. Integration with Claude Code (Capsules 04-05)

Connecting your server to Claude Code and solving problems:

Integration with Claude Code:
├── Configuration
│   ├── Settings files (user vs project)
│   ├── Configuration formats
│   ├── Permissions and scopes
│   └── Multiple servers
├── Verification
│   ├── Does Claude Code see your server?
│   ├── Can Claude Code invoke your tools?
│   └── Are the results correct?
└── Troubleshooting
    ├── Connection errors
    ├── Permission denied
    ├── Tool not found
    ├── Timeout
    └── Invalid response format

Module objective

By the end of this module, you'll be able to:

✅ Write unit tests for MCP tools and resources using Vitest (TypeScript) and pytest (Python)
✅ Write integration tests that verify the complete client-server flow
✅ Use MCP Inspector for visual and interactive debugging
✅ Implement effective logging in MCP servers without breaking the stdio protocol
✅ Configure MCP servers in Claude Code — settings, permissions, verification
✅ Diagnose and resolve the most common connection and execution errors
✅ Build a complete test suite like the one you'll need in the Module 8 project

Module roadmap

Capsule	Topic	What you'll learn
02	Testing MCP Servers	Unit tests, integration tests, error handling tests with Vitest and pytest
03	Debugging: Tools	Advanced MCP Inspector, logging, request tracing
04	Configuring Claude Code	Settings files, scopes, permissions, verification, multiple servers
05	Troubleshooting and Errors	Common errors, diagnosis, solutions + mini-project: a complete test suite

Learning flow

The progression is deliberate:

Testing (capsule 02) — first you learn to verify that your code works. Without tests, you can't trust that the changes in the following capsules don't break anything.
Debugging (capsule 03) — when a test fails, you need tools to find the problem. MCP Inspector and logging are your allies.
Configuring Claude Code (capsule 04) — with passing tests and debugging tools ready, you connect your server to Claude Code. If something fails, you already know how to diagnose it.
Troubleshooting (capsule 05) — the reference guide for the problems you'll encounter in real life, plus a mini-project that integrates everything.

Each capsule builds on the previous one. The tests from capsule 02 help you verify that the configuration from capsule 04 works. The logging from capsule 03 helps you resolve the errors from capsule 05.

The complete arc: from Phase 2 to Phase 3

So you understand the magnitude of the transition:

Phase 2 — "I can build an MCP server":
├── Functional server ✅
├── Tools that return results ✅
├── Resources that expose data ✅
├── MCP Inspector for manual testing ✅
├── Automated tests ❌
├── Logging for diagnosis ❌
├── Configuration verified in Claude Code ❌
├── Documented troubleshooting ❌
└── Confidence to use in real flows ❌

Phase 3 — "I can trust my MCP server":
├── Everything above ✅
├── Automated test suite ✅
├── Logging that records requests and errors ✅
├── Verified Claude Code configuration ✅
├── Troubleshooting guide for common errors ✅
└── Confidence to use in production ✅

Phase 3 doesn't change your code — it changes your confidence in your code. And that confidence comes from evidence: tests that pass, logs that confirm, and configurations you verify.

Connection to the capstone project (Module 8)

Module 8 asks you to build a production-ready MCP server. "Production-ready" means, among other things:

A complete test suite — unit tests + integration tests
Logging — knowing what happened when something fails
Verified configuration — Claude Code connected and working
Robust error handling — clear messages, error recovery

You learn all of this in this module. The test suite you write in capsule 05 (mini-project) is the template for the Module 8 test suite. The Claude Code configuration you do in capsule 04 is the same one you need in the final project.

Module 7 → Module 8:
├── Tests (capsule 02)                → Project's test suite
├── Logging (capsule 03)              → Server logging in production
├── Claude Code configuration (04)    → Final project setup
├── Troubleshooting (capsule 05)      → Reference to solve problems
└── Mini-project (capsule 05)         → Template for the project's test suite

If you do this module well, Module 8 is assembly. If you skip it, Module 8 is an obstacle course.

Tools you'll use in this module

Tool	What you use it for
Vitest	Testing framework for TypeScript/JavaScript
pytest	Testing framework for Python
MCP Inspector	Visual and interactive debugging of MCP servers
Claude Code	The host that consumes your MCP server
Node.js / Python	Runtimes of your MCP servers
npx	Run MCP Inspector without a global installation

You don't need to install everything now — each capsule guides you step by step.

Prerequisites

For this module you need:

✅ Modules 4-6 completed — at least one functional MCP server in TypeScript or Python
✅ Node.js v18+ — node --version
✅ Python 3.10+ (if you use Python) — python --version
✅ Claude Code installed — claude --version
✅ Your own MCP server to test and debug

Prior knowledge

You don't need prior experience with testing frameworks. Capsule 02 starts from scratch with Vitest and pytest. If you already have testing experience, you'll move faster, but it's not required.

Boundaries: what is NOT covered in this module

❌ Deploy to cloud — Deploying to production (cloud, Docker) isn't part of this guide's scope
❌ CI/CD pipelines — Continuous integration is the topic of another guide
❌ Performance testing — Load testing and benchmarks are outside the scope
❌ Security testing — Penetration testing and security audits are specialized topics
❌ MCP Apps UI testing — Testing visual interfaces requires specific tools
❌ Remote transport testing — HTTP/SSE testing requires additional infrastructure setup

This module covers functional testing, debugging, and configuration. It's what you need to go from "it works" to "it works reliably."

Comparison of testing tools

Before starting, an overview of the tools you'll use and why:

For TypeScript: Vitest

Why Vitest and not Jest?
├── Native compatibility with TypeScript (no extra configuration)
├── ESM support out of the box (the MCP SDK uses ESM)
├── Faster than Jest for TypeScript projects
├── API compatible with Jest (if you already know Jest, you know Vitest)
└── watch mode for iterative development

For Python: pytest

Why pytest and not unittest?
├── Cleaner syntax (functions, not classes)
├── Fixtures for reusable setup/teardown
├── Plugins for async testing (pytest-asyncio)
├── Better error output
└── The de facto standard in the Python community

Both tools are configured from scratch in capsule 02. You don't need prior experience with either.

Signs of success

By the end of this module, you'll know you succeeded if:

✅ You have a test suite with at least 10 tests for an MCP server (tools + resources + error handling)
✅ You can use MCP Inspector to diagnose why a tool doesn't work
✅ Your MCP server has logging that tells you which requests it received and which errors it encountered
✅ Claude Code has your server configured and you can verify it with /mcp
✅ You can diagnose and resolve the 5 most common errors without searching on Google
✅ You can run npm test or pytest and see all your tests pass green

Mindset for this module

This module requires a mindset shift. In modules 4-6, the feedback was immediate and visual: you run the server, open MCP Inspector, see that it works, satisfaction. Testing and debugging are different: the feedback is less visible but more valuable.

Three principles:

A test that fails is more valuable than a test that passes. When a test fails, you found a bug before Claude Code found it. That's a win.
Logging isn't debugging — it's prevention. You don't add logging when you have a bug. You add logging before, so that when the bug appears, the log tells you exactly where it is.
The Claude Code configuration is the moment of truth. All the work of modules 4-6 converges here. When Claude Code invokes your tool and returns the correct result, you complete the loop: you designed, built, tested, and connected an MCP server. You built it, and Claude Code uses it.

Frequently asked questions before starting

"Do I need to test in both languages (TypeScript and Python)?"

No. If you only built a server in one language, test that one. Capsule 02 shows Vitest for TypeScript and pytest for Python. Choose the one that applies to your server. If you built in both, the capsule covers both.

"Aren't MCP Inspector and manual tests enough?"

MCP Inspector is excellent for interactive debugging, but it's not a substitute for automated tests. Inspector tells you "it works now." Tests tell you "it keeps working after every change." You need both.

"How long does it take to write a test suite?"

For an MCP server with 3-4 tools and 2-3 resources, a basic test suite (happy path + error cases) takes ~30-45 minutes. It's an investment that pays off the first time it detects a bug.

"Do I need to configure Claude Code now or can I do it later?"

Capsule 04 guides you step by step. If you already have your server configured in Claude Code from previous modules, the capsule helps you verify that the configuration is correct and complete.

Summary

This module starts Phase 3: Production — from "it works" to "it works reliably"
Testing isn't bureaucracy — it's an investment that detects bugs before Claude Code finds them
Three layers: automated testing (Vitest/pytest), debugging (MCP Inspector/logging), integration (Claude Code configuration)
The module is a direct prerequisite of Module 8 — the test suite and configuration you do here are the base of the capstone project
Each capsule builds on the previous one: tests → debugging → configuration → troubleshooting
The mindset is one of professionalism: "this is how serious developers ensure their code works"

Additional resources

Vitest Documentation — Testing framework you'll use for TypeScript
pytest Documentation — Testing framework for Python
MCP Inspector — Visual debugging tool for MCP servers
MCP TypeScript SDK — Testing — Official SDK with testing examples
MCP Python SDK — Official SDK for Python
Claude Code MCP Configuration — Official documentation of MCP configuration in Claude Code

Next capsule: Testing MCP Servers — unit tests, integration tests, and error handling tests with Vitest and pytest. Real tests for real MCP servers.

← PreviousProject: MCP App with an Interactive Dashboard Next →Testing MCP Servers