Testing with Gemini CLI

Testing a custom MCP server requires three layers. Unit tests verify individual tool handler functions with mocked dependencies — standard software testing. Integration tests verify the server process starts, responds to JSON-RPC messages, and returns correctly structured responses — use the MCP Inspector or the SDK's test client. End-to-end tests verify the server works within Gemini CLI — configure it in settings.json, launch Gemini, and validate that tools appear and produce correct results.

The MCP Inspector is the single most valuable testing tool. It launches your server, connects over stdin/stdout, displays all registered tools and resources, and lets you call tools interactively with custom parameters. Use it during development as a rapid feedback loop: change code, restart the inspector, test the tool, verify the response. The inspector also validates JSON-RPC compliance — if your server works in the inspector, it will work in Gemini CLI.

# Layer 1: Unit tests (standard test runner)
npx vitest run src/tools/*.test.ts

# Layer 2: Integration tests with MCP Inspector
npx @modelcontextprotocol/inspector node ./dist/index.js
# Opens browser UI — test each tool manually
# Verify: tool list matches expected, parameters validate, responses are structured

# Layer 3: End-to-end with Gemini CLI
# Add to .gemini/settings.json, then:
gemini -p "List the available tools from the internal-api server" \
  --output-format json > tools-check.json

# Automated E2E test script
gemini -p "Use the get_customer tool to look up customer abc-123. \
  Return only the customer name and MRR." \
  --output-format json > e2e-result.json

# Validate the response
node -e "
  const r = require('./e2e-result.json');
  console.assert(r.includes('abc-123'), 'Customer ID not found in response');
  console.log('E2E test passed');
"