How to Test and Debug MCP Servers

Bottom line: A server that works once is not enough. Reliable MCP servers need repeatable tests, visible logs, and a quick way to reproduce failures.

Why testing MCP servers is different

An MCP server sits between an AI client and your backend. The client sends JSON over a transport, the server parses it, runs your code, and returns JSON. That means bugs can hide in the schema, the transport, the handler logic, or the environment.

Good testing covers all four layers: schema validation, handler correctness, transport wiring, and end-to-end behavior with a real client.

The MCP Inspector

The fastest way to verify a server is the MCP Inspector. Install it globally and point it at your compiled server.

npm install -g @modelcontextprotocol/inspector
npx @modelcontextprotocol/inspector node dist/index.js

The Inspector opens a web UI that lists your tools, shows the JSON schema for each one, and lets you fill in arguments and call the tool. Use it to confirm that descriptions are clear and that valid inputs return the expected shape.

Logging without breaking the protocol

MCP uses stdout for protocol messages, so logging to stdout will corrupt the connection. Always log to stderr.

function log(level: string, message: string) {
  console.error(`[${level}] ${new Date().toISOString()} ${message}`);
}

Add a --verbose flag so operators can turn on detailed logs without overwhelming normal output. Include the request ID, the tool name, and a redacted version of arguments for security.

Unit testing tool handlers

Keep your handler logic in pure functions that do not depend on the MCP transport. Then test them like any other function.

import { describe, it, expect } from 'vitest';
import { manageTodos } from './tools.js';
  import ArticleMeta from '$lib/components/ArticleMeta.svelte';

describe('manageTodos', () => {
  it('adds a todo', () => {
    const result = manageTodos({ action: 'add', text: 'test' });
    expect(result.total).toBe(1);
  });

  it('throws when text is missing for add', () => {
    expect(() => manageTodos({ action: 'add' })).toThrow();
  });
});

Debugging schema mismatches

If a client rejects your tool result, the first thing to check is whether your output matches the schema the client expects. Return content as an array of objects with a type and text field.

return {
  content: [{ type: 'text', text: JSON.stringify(result) }]
};

Common mistakes include returning a plain string, omitting the content key, or returning unsupported content types.

End-to-end testing with a real client

Once unit tests pass, add the server to Claude Desktop or Cursor and try a few natural-language requests. Watch the logs to confirm the right tool is called with sensible arguments. If the model calls the wrong tool, improve the tool description.

CI/CD checklist

• Type-check and lint the project on every pull request.
• Run unit tests for every handler.
• Start the server and run the Inspector in headless mode to verify tool discovery.
• Confirm the built artifact can be launched with the documented command.
• Check that no secrets are logged to stderr.

Published 2026-06-12