Testing and Debugging

This guide covers how to verify your MCP server works correctly before connecting it to oHallo, and how to debug issues once it is live.

Testing locally with curl

MCP servers use JSON-RPC 2.0 over HTTP. All requests are POST to the /mcp endpoint with a JSON body. You need three things in every request:

Content-Type: application/json header
Authorization: Bearer <your-key> header (if authType is api_key)
A JSON-RPC body with jsonrpc, id, method, and params

Start your server locally first:

MCP_API_KEY=test-key npx tsx src/server.ts

Verify tool registration with tools/list

The first thing to test is whether your tools are registered correctly. This is the same call that oHallo makes when you add an MCP server in the dashboard:

curl -s http://localhost:4100/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer test-key" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }' | jq .

Check the response:

Every tool you defined should appear in result.tools
Each tool should have name, description, and inputSchema
All required fields should be listed in inputSchema.required
Note: tenantId and workspaceId are injected by MCP Hub at call time — they do not need to appear in your schema

If a tool is missing, verify that it is included in the tools array passed to createMcpServer.

Test individual tools with tools/call

Call each tool with realistic test data. When testing locally, you can include tenantId and workspaceId in the arguments to simulate what MCP Hub would inject in production:

curl -s http://localhost:4100/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer test-key" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "get_customer",
      "arguments": {
        "tenantId": "test-account",
        "workspaceId": "test-workspace",
        "customerId": "cust_001"
      }
    }
  }' | jq .

A successful response looks like:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"id\":\"cust_001\",\"name\":\"Acme Corp\",\"email\":\"billing@acme.com\"}"
      }
    ]
  }
}

The tool’s return value is serialised as a JSON string inside result.content[0].text.

Test error cases

Test every error path your tool can produce:

# Test not_found error
curl -s http://localhost:4100/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer test-key" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "get_customer",
      "arguments": {
        "tenantId": "test-account",
        "workspaceId": "test-workspace",
        "customerId": "nonexistent"
      }
    }
  }' | jq .

An error response from McpError will appear as an error in the JSON-RPC response. Verify that the error type and message match what you expect.

Test authentication

Verify that requests without a valid token are rejected:

# No auth header -- should be rejected
curl -s http://localhost:4100/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/list",
    "params": {}
  }' | jq .

# Wrong token -- should be rejected
curl -s http://localhost:4100/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer wrong-key" \
  -d '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools/list",
    "params": {}
  }' | jq .

Both should return an authentication error, not your tool data.

Checking tool call logs in oHallo

Once your MCP server is connected to oHallo and handling live conversations, you can inspect tool calls from the dashboard:

Go to Settings then Agents.
Click on the agent that uses your MCP tools.
Select View Executions to see recent agent runs.
Each execution shows which tools were called, the arguments passed, the response received, and the execution time.

This is the fastest way to diagnose issues like “the agent called the wrong tool” or “the agent passed unexpected arguments”.

Agent observability API

You can also query tool call data programmatically using the oHallo API. This is useful for building monitoring dashboards or alerting on failures.

List recent agent executions:

curl -s https://api.ohallo.eu/api/agent-executions?limit=10 \
  -H "Authorization: Bearer sf_live_v1_your_key_here" | jq .

Response:

{
  "executions": [
    {
      "id": "exec_abc123",
      "agentId": "agent_order_lookup",
      "conversationId": "conv_def456",
      "status": "completed",
      "startedAt": "2026-03-25T14:30:00Z",
      "completedAt": "2026-03-25T14:30:02Z",
      "toolCalls": [
        {
          "id": "tc_ghi789",
          "toolName": "get_order",
          "mcpServerName": "my-erp",
          "arguments": { "orderNumber": "ORD-48291" },
          "result": { "orderNumber": "ORD-48291", "status": "shipped" },
          "durationMs": 245,
          "status": "success"
        }
      ]
    }
  ]
}

Get tool calls for a specific execution:

curl -s https://api.ohallo.eu/api/agent-executions/exec_abc123/tool-calls \
  -H "Authorization: Bearer sf_live_v1_your_key_here" | jq .

This returns the full list of tool calls in the execution, including arguments, results, timing, and any errors.

Common issues

Tool not found

Symptom: The agent reports it cannot find the tool, or the tool does not appear when you add the MCP server.

Causes:

The tool name in the tools array does not match what the agent is trying to call. Tool names are case-sensitive.
The server is not running or is not reachable from oHallo’s network.
The /mcp endpoint is not responding to tools/list.

Fix: Run tools/list manually and verify the tool name appears exactly as expected. Check that the server URL in oHallo includes the /mcp path.

Authentication failure

Symptom: oHallo shows “Authentication failed” when trying to connect to your MCP server, or tool calls return authentication errors.

Causes:

The MCP_API_KEY environment variable is not set on your server.
The API key registered in oHallo does not match the key your server expects.
The authType in createMcpServer is set to 'none' but oHallo is sending a token, or vice versa.

Fix: Verify the MCP_API_KEY environment variable is set and matches the key configured in oHallo. Test with curl using the same key.

Tool call timeout

Symptom: Tool calls fail with a timeout error. The agent reports that the tool did not respond.

Causes:

Your tool handler takes too long to execute. MCP tool calls must complete within 30 seconds.
Your server is making a slow downstream API call without a timeout.
Network latency between oHallo and your server is too high.

Fix: Add timeouts to all downstream calls in your tool handlers. If a query is inherently slow, consider caching or pre-computing results. Profile your handler to find the bottleneck.

Unexpected tool arguments

Symptom: Your tool receives arguments it does not expect, or required arguments are missing.

Causes:

The agent is extracting information from the customer’s message and may interpret values differently than expected. For example, a customer saying “order twelve thirty-four” might be passed as "1234" or "twelve thirty-four".
Your input schema description is ambiguous, causing the agent to pass the wrong type of data.

Fix: Improve your parameter descriptions with explicit format examples (e.g. "The order number, format ORD-XXXXX, e.g. ORD-48291"). Validate inputs in your handler and throw McpError('validation_error', ...) with a clear message about the expected format.

Empty or unhelpful responses

Symptom: The agent’s response to the customer is vague or missing details, even though your tool returns the correct data.

Causes:

Your tool returns data with unclear field names (e.g. dt_est instead of estimatedDelivery).
Your tool returns too much data, and the agent cannot identify the relevant parts.
Your tool returns a flat string instead of structured data.

Fix: Return structured objects with descriptive field names. Include units and context (e.g. { amount: 149.99, currency: 'EUR' } instead of { total: 149.99 }). Keep responses focused on what the tool’s description promises.

Debug checklist

Use this checklist when your MCP server is not working as expected:

Can you reach the server? Curl the /mcp endpoint from a machine that can reach it. Check firewall rules and DNS.
Does tools/list return your tools? If not, the server is not started or the tools are not registered.
Does authentication work? Test with the correct key, a wrong key, and no key.
Does tools/call return the expected data? Test with known good inputs.
Does error handling work? Test with invalid inputs and verify you get structured errors, not stack traces.
Is the server fast enough? Tool calls must complete within 30 seconds. Add console.time around slow operations.
Are descriptions specific enough? Vague descriptions cause the planning agent to skip your tools or pass wrong arguments.
Is the response structured? Flat strings are harder for agents to use than structured objects.

Next steps

Build an MCP Server — if you have not built your first server yet
Tool Schema — improve your input schemas and return values
Building a Custom Agent — create an agent that uses your tools