Ports and the effective port

The root receiver prefers port 4317 for gRPC and port 4318 for HTTP. These are the standard collector ports, so an SDK or an example finds the root without configuration.

What happens when a port is busy

A Docker port forward or another collector often holds 4317 or 4318. The root then moves along a fixed ladder. The ladder adds 10000, then 20000, to the busy port.

Preferred	Second try	Third try
4317	14317	24317
4318	14318	24318

The ladder gives the same port at every launch, so a config that you write once keeps working. When every ladder port is busy too, the root takes a port from the operating system. That port changes at each launch.

Copy the effective port

Do not assume 4317. Open Collectors → Local OTLP receiver → Connection and copy the port the app shows now. That is the effective port.

Read the port with your AI tool

The MCP server answers with the effective ports. Ask your AI coding tool to call get_receiver_info, or tell it “ask Loggerhead which port to send telemetry to”. The fields otlpGrpcPort and otlpHttpPort hold the effective ports. The flags otlpGrpcPortConflict and otlpHttpPortConflict are true after a move.

{"otlpGrpcPort":4317,"otlpHttpPort":4318,
 "otlpGrpcConfiguredPort":4317,"otlpHttpConfiguredPort":4318,
 "otlpGrpcPortConflict":false,"otlpHttpPortConflict":false}

See Tools reference for the full answer, and Local endpoints for what else the app serves on loopback.

Find what holds the port

Open Terminal and run this command. It lists the process on each of the two ports.

lsof -nP -iTCP -sTCP:LISTEN | grep -E ':(4317|4318) '

Quit that process, or keep it and use the effective port. Both work.