Go Slow Time Server¶

Overview¶

The slow-time-server is a configurable-latency Go-based MCP server designed for timeout, resilience, and load testing. Modelled on the fast-time-server, it introduces artificial latency on every tool call and serves as a testing target for:

• Gateway timeout enforcement – verify that per-tool timeout_ms overrides work correctly
• Circuit breaker behaviour – trigger and observe circuit breaker state transitions
• Session pool resilience – stress-test connection pools under slow-response conditions
• Load testing – simulate realistic slow-tool scenarios with configurable latency distributions

Key Highlights:

• Configurable latency: fixed, uniform, normal, or exponential distributions
• 5 MCP tools with different latency profiles (instant, slow, timeout, flaky)
• Runtime reconfiguration via REST API
• Failure simulation with configurable rate and mode
• Invocation statistics with p50/p95/p99 percentiles
• Single static binary (~2 MiB), scratch Docker image

Installation¶

Using Docker Compose (Recommended)¶

The slow-time-server is included in the resilience profile:

docker compose --profile resilience up -d

This starts the server on port 8889 (mapped from container port 8081) and automatically registers it with the gateway.

From Source¶

cd mcp-servers/go/slow-time-server
make build
./dist/slow-time-server -transport=dual -port=8081 -latency=5s

Environment Variables¶

Transport Modes¶

1. STDIO Mode (Default)¶

For desktop MCP clients:

./slow-time-server -transport=stdio -latency=5s

2. Dual Mode¶

Both MCP (SSE + Streamable HTTP) and REST API:

./slow-time-server -transport=dual -port=8081 -latency=5s

Endpoints:

• /sse – MCP SSE events
• /messages – MCP SSE messages
• /http – MCP Streamable HTTP (JSON-RPC)
• /api/v1/* – REST API endpoints
• /health – Health check (always instant)

3. REST Mode¶

REST API only (no MCP protocol):

./slow-time-server -transport=rest -port=8081

MCP Tools¶

get_slow_time¶

Returns the current time with configurable delay. This is the primary tool for testing timeout behaviour.

Parameters:

• timezone (optional): IANA timezone name (default: "UTC")
• delay_seconds (optional): Override delay in seconds (default: server's configured latency)

Example:

{
  "tool": "get_slow_time",
  "arguments": {
    "timezone": "America/New_York",
    "delay_seconds": 10
  }
}

convert_slow_time¶

Converts time between timezones with delay.

Parameters:

• time (required): RFC3339 time string to convert
• source_timezone (required): Source IANA timezone
• target_timezone (required): Target IANA timezone
• delay_seconds (optional): Override delay in seconds

get_instant_time¶

Returns the current time with zero delay. Useful as a baseline to compare against slow tools.

Parameters:

• timezone (optional): IANA timezone name (default: "UTC")

get_timeout_time¶

Returns the current time after a 10-minute delay. Designed to always exceed any reasonable timeout, useful for testing that the gateway correctly enforces timeouts.

Parameters:

• timezone (optional): IANA timezone name (default: "UTC")

get_flaky_time¶

Returns the current time but randomly fails based on the server's configured failure rate. Use this to test circuit breaker behaviour.

Parameters:

• timezone (optional): IANA timezone name (default: "UTC")

Failure modes:

• timeout – Simulates a stuck request (context sleep for 10 minutes)
• error – Returns an MCP error result
• panic – Returns a panic-style error message

MCP Resources¶

latency://config¶

Current server latency configuration including distribution type, default latency, failure rate, and failure mode.

latency://stats¶

Invocation statistics: total count, failure count, average latency, and p50/p95/p99 percentiles.

MCP Prompts¶

test_timeout¶

Generates step-by-step instructions for testing timeout behaviour.

Parameters:

• delay_seconds (optional): Delay to use in the test (default: "30")
• timeout_seconds (optional): Expected timeout threshold (default: "10")

REST API¶

Available in dual and rest transport modes:

Runtime Reconfiguration¶

Update latency settings at runtime without restarting:

curl -X POST http://localhost:8889/api/v1/config \
  -H "Content-Type: application/json" \
  -d '{
    "default_latency": "10s",
    "distribution": "normal",
    "mean_latency": "5s",
    "stddev_latency": "2s",
    "failure_rate": 0.1,
    "failure_mode": "error"
  }'

Latency Distributions¶

The server supports four latency distribution models:

# Fixed 5s latency
./slow-time-server -transport=dual -port=8081 -latency=5s

# Uniform between 1-10s
./slow-time-server -transport=dual -port=8081 \
  -latency-distribution=uniform -latency-min=1s -latency-max=10s

# Normal distribution (realistic)
./slow-time-server -transport=dual -port=8081 \
  -latency-distribution=normal -latency-mean=5s -latency-stddev=3s

# Exponential (models network jitter)
./slow-time-server -transport=dual -port=8081 \
  -latency-distribution=exponential -latency-mean=5s

Testing Scenarios¶

Timeout Testing¶

Verify the gateway enforces per-tool timeouts:

# Start with 5s latency (exceeds typical 3s gateway timeout)
./slow-time-server -transport=dual -port=8081 -latency=5s

# Register with gateway, then set a per-tool timeout override
curl -X PATCH http://localhost:4444/tools/<get_slow_time_tool_id> \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"timeout_ms": 3000}'

# Calls to get_slow_time should now return ToolTimeoutError after 3s

Circuit Breaker Testing¶

Trigger circuit breaker transitions with a high failure rate:

# 30% failure rate with error mode
./slow-time-server -transport=dual -port=8081 \
  -latency=2s -failure-rate=0.3 -failure-mode=error -seed=42

# Call get_flaky_time repeatedly to observe circuit breaker opening

Load Testing with Locust¶

A Locust test file is provided at tests/loadtest/locustfile_slow_time_server.py with four user classes:

# Via docker compose (testing profile includes Locust)
docker compose --profile resilience up -d

# Or run directly
locust -f tests/loadtest/locustfile_slow_time_server.py \
  --host=http://localhost:8889 \
  --users=10 --spawn-rate=2 --run-time=120s --headless

Docker¶

# Build
cd mcp-servers/go/slow-time-server
make docker-build

# Run with default 5s latency
docker run --rm -p 8081:8081 slow-time-server:latest

# Run with custom latency and failure rate
docker run --rm -p 8081:8081 \
  -e DEFAULT_LATENCY=30s \
  -e FAILURE_RATE=0.3 \
  slow-time-server:latest

Gateway Registration¶

# Register via gateway API
curl -X POST http://localhost:4444/gateways \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "slow_time",
    "url": "http://slow-time-server:8081/http",
    "transport": "STREAMABLEHTTP"
  }'

# Override timeout for the guaranteed-timeout tool
curl -X PATCH http://localhost:4444/tools/<get_timeout_time_id> \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"timeout_ms": 5000}'

Related Resources¶

• Fast Time Server – The baseline fast-response counterpart
• Performance Testing – Load testing guide
• Source code