Testing & Debugging

MCP Inspector

The official MCP Inspector is a web-based tool for testing MCP servers interactively.

Setup

npx @modelcontextprotocol/inspector

Connect to your MCP server:

• URL: http://localhost:8080/mcp
• Transport: Streamable HTTP
• Auth: Bearer token from MCP_API_KEY_MAPPINGS (also accepts X-API-Key header)

Note: CORS is configured to allow any origin (Access-Control-Allow-Origin: *), so the MCP Inspector can connect without cross-origin issues. The CrossOriginProtection check is bypassed for preflight requests.

What you can do

• Browse all 31 tools with auto-generated schemas
• Call tools interactively with form-based input
• Inspect JSON-RPC request/response pairs
• Test error handling and edge cases (including INTENT_REQUIRED for update_member_email/update_member_phone)

NEMT MCP Test Agent

Our custom test agent at nemt-mcp-test-agent/ provides AI-powered testing beyond what the Inspector offers.

Quick Start

cd nemt-mcp-test-agent
npm install
cp .env.example .env  # Configure OPENAI_API_KEY, MCP_SERVER_URL, MCP_AUTH_TOKEN
npm run dev

Testing Modes

1. Single-Prompt Tests (/test:*)

Fast, deterministic tool-level checks:

Command	What it tests
/test:booking-happy	Full booking: verify → address → details → review → confirm
/test:staging-roundtrip	Roundtrip with will-call using staging data (ABOBA-1)
/test:mr-booking	Mileage reimbursement: verify → address → details → list_drivers → assign_driver → review → confirm
/test:companion	Booking with companion_name + companion_type
/test:requester	Third-party requester fields
/test:cancel	Cancel flow: get_active_trips → cancel_trip (no reason) → cancel_trip (reason)
/test:will-call	Will-call: get_active_trips → activate_will_call
/test:standing-orders	Standing order CRUD
/test:search	Member search with PII masking
/test:profile	Full member profile after verification
/test:sequence	Sequence gates: confirm without review, review without details
/test:errors-all	Error handling across all 31 tools

2. Conversational Tests (/convo:*)

Multi-turn phone call simulation with AI scoring:

Command	Scenario
/convo:aboba	Staging roundtrip with will-call
/convo:aboba-mr	Staging mileage reimbursement with driver selection
/convo:eleanor	Wheelchair dialysis roundtrip
/convo:james	Nervous caller with companion
/convo:melody	Post-dialysis will-call activation
/convo:diane	Anxious status check, wants driver ETA
/convo:all	Run all personas with scoring

Two AI models play different roles:

• Sarah (agent) — follows booking workflow, calls MCP tools
• Member (persona) — responds naturally as a real caller

After each conversation, an AI analyzer scores on 4 dimensions:

• Tool Response Quality (1-10)
• System Prompt Effectiveness (1-10)
• Error Handling (1-10)
• Conversation Naturalness (1-10)

3. Free-Form Prompts

Type any natural language test scenario:

> Test what happens when I call confirm_trip without doing review_trip first

Environment Configuration

Variable	Default	Description
MCP_ENV	staging	Test data: staging (ABOBA-1) or production
MCP_SERVER_URL	—	MCP server endpoint
MCP_AUTH_TOKEN	—	Bearer token
OPENAI_MODEL	gpt-4o	AI model for test agent

Alternative Testing Tools

curl

Direct JSON-RPC calls:

# Initialize (optional for stateless mode)
curl -X POST http://localhost:8080/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

# Using X-API-Key header (alternative)
curl -X POST http://localhost:8080/mcp \
  -H "X-API-Key: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

# Call a tool
curl -X POST http://localhost:8080/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","id":2,"params":{"name":"verify_member","arguments":{"member_id":"ABOBA-1","dob":"12/01/2025","channel":"voice_call"}}}'

Claude Desktop / Cursor / VS Code

MCP-compatible editors can connect directly:

1. Add to your MCP config:

{
  "mcpServers": {
    "nemt": {
      "url": "http://localhost:8080/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

2. Tools appear automatically in the editor’s tool list

Health Check

curl http://localhost:8080/healthz
# {"status":"ok","spanner":"ok","valkey":"ok"}

Debug Logging

All tool calls are logged to stdout in structured JSON:

{
  "level": "info",
  "audit": true,
  "method": "tools/call",
  "tool_name": "verify_member",
  "outcome": "allowed",
  "org_id": "org-123",
  "request_id": "uuid",
  "duration": "156ms"
}

Test agent logs to nemt-mcp-test-agent/logs/ in JSONL format with full request/response bodies.