Skip to main content

Run Over HTTP Transport

By default ThoughtJack uses stdio (JSON-RPC over stdin/stdout). The HTTP transport uses MCP Streamable HTTP for network-based testing.

Start with HTTP​

thoughtjack run my_scenario.yaml --mcp-server 127.0.0.1:8080

This binds an HTTP server at http://127.0.0.1:8080/mcp.

Specify host and port​

# Bind to all interfaces
thoughtjack run my_scenario.yaml --mcp-server 0.0.0.0:8080

# Bind to specific interface
thoughtjack run my_scenario.yaml --mcp-server 192.168.1.100:3000

Test with curl​

Send an MCP initialize request to the /mcp endpoint:

curl -X POST http://127.0.0.1:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": { "name": "test-client", "version": "1.0.0" }
    }
  }'

The response includes an Mcp-Session-Id header. Pass it on subsequent requests to maintain the session:

curl -X POST http://127.0.0.1:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: <session-id-from-init>" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

Responses are returned as SSE event: message frames with data: containing the JSON-RPC response.

When to use HTTP​

Use caseTransport
Testing a single MCP clientstdio
Testing multiple concurrent clientsHTTP
Automated test suites with HTTP clientsHTTP
Integration with MCP clients that spawn subprocessesstdio
Browser-based or remote testingHTTP

Combining with other flags​

All run flags work with HTTP transport:

thoughtjack run \
  my_scenario.yaml \
  --mcp-server 127.0.0.1:8080 \
  --events-file events.jsonl \
  --progress on

Note: The pipe_deadlock side effect only works with stdio transport and is silently skipped on HTTP.