Testing & Debugging Extensions

Extension testing happens at three levels: unit tests for individual tool handlers, integration tests for the MCP server, and end-to-end tests with Gemini CLI. Unit tests validate that your tool logic works correctly — given this input, produce this output. Integration tests validate that the MCP server speaks the protocol correctly — tool listing, tool calling, error handling. End-to-end tests validate that Gemini CLI can install, activate, and use your extension in a real session.

The MCP Inspector (npx @modelcontextprotocol/inspector) is your primary debugging tool. It connects to your MCP server and lets you call tools manually, inspect schemas, and see raw JSON-RPC messages. When a tool is not being called correctly by Gemini CLI, the Inspector shows you exactly what the server is advertising versus what the model is sending. Nine out of ten debugging sessions end with a schema mismatch — a required field the model is not providing, or a description that misleads the model into sending wrong inputs.

# Run the MCP Inspector against your local server
npx @modelcontextprotocol/inspector node server.js

# Test with a local install in Gemini CLI
gemini extensions install /path/to/my-extension
gemini  # start a session and test tool usage

# Debug MCP communication with verbose logging
GEMINI_LOG_LEVEL=debug gemini
# Watch for tool/list responses and tool/call requests

# Unit test a tool handler directly
node -e "
  import { handleQuery } from './handlers.js';
  const result = await handleQuery({ sql: 'SELECT 1', limit: 10 });
  console.log(JSON.stringify(result, null, 2));
"

1. Unit test tool handlers Extract handler functions from the MCP server and test them independently. Mock external dependencies (APIs, databases) to test logic in isolation.
2. Integration test with Inspector Use the MCP Inspector to verify your server lists tools correctly, accepts valid inputs, rejects invalid inputs, and returns well-structured results.
3. End-to-end test with local install Install your extension locally in Gemini CLI and run real prompts that should trigger your tools. Verify the model selects the right tool, sends correct inputs, and presents results clearly.