Connect your project with one prompt

After you add the Loggerhead MCP server, your AI tool can read what Loggerhead stores. It can also do the other half of the job. It can connect the project’s own telemetry to Loggerhead and prove that the data arrives.

Before you start

Open the Loggerhead app.
Add the MCP server to your AI tool. See Claude Code, Cursor, Codex, Windsurf, or Other MCP clients.
Optional. Open Collectors → Local OTLP receiver → Connection and note the two OTLP addresses. The defaults are http://127.0.0.1:14317 for gRPC and http://127.0.0.1:14318 for HTTP. The prompt tells the AI tool to read the effective addresses with get_receiver_info, so you do not have to copy them. Use the addresses from the app to check the AI tool’s report. See Ports and the effective port.

The prompt

Open the chat in your AI tool, inside the project, and paste this prompt.

Connect this project's telemetry to Loggerhead and prove that it works.

Loggerhead runs on this Mac. It receives OpenTelemetry (OTLP) over gRPC and over HTTP on
127.0.0.1. The ports can change, so do not assume the defaults 14317 and 14318.

You have the Loggerhead MCP server. Its tools read what Loggerhead has stored:
query_logs, query_metrics, query_traces, get_trace, get_receiver_info, and the resource
loggerhead://stats.

Do this, in order:

1. Call get_receiver_info. Use grpcEndpoint as the gRPC address and httpEndpoint as the HTTP
   address for every step below. Then read loggerhead://stats. Note the counts of logs, metrics,
   and spans. This is the baseline.
2. Find how this project produces logs, metrics, and traces today. Look for an OpenTelemetry SDK,
   a logging library, a metrics library, and any exporter or collector config.
3. Make the project export logs, metrics, and traces to Loggerhead over OTLP. Use the OpenTelemetry
   SDK for the project's language. Set the service name to the project name. Prefer the environment
   variables OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_SERVICE_NAME, or the project's existing config,
   over hard-coded values. Set the endpoint to the address from step 1. Keep the change small.
   Do not send telemetry anywhere else.
4. Start the project, or run its tests, so that it emits at least one log record, one metric,
   and one trace. Then stop it.
5. Read loggerhead://stats again. Call query_logs, query_metrics, and query_traces for the last
   10 minutes, filtered to this service name. Confirm that each count went up and that the records
   carry this service's name. Call get_trace on one trace ID and confirm that the spans look right.
6. Report the addresses from step 1. Report what you changed, file by file. Report what you ran.
   Report what each of the three signals shows in Loggerhead. If a signal did not arrive, say
   which one and what you tried.

What happens next

The AI tool calls get_receiver_info to read the effective OTLP addresses from the running app. It reads the project and picks the OpenTelemetry SDK for its language. It adds the exporter, points it at the root receiver, and runs the project once. Then it calls the four query tools to check that logs, metrics, and traces arrived. The report at the end tells you which signals work and which do not.

Review the code change before you commit it. The tool writes real code in your project.

If a signal does not arrive

The counts do not change. Confirm that the Loggerhead app is open. Compare the addresses in the AI tool’s report with Collectors → Local OTLP receiver → Connection. Open Logs in the app and look for new records.
The service name is wrong. Open Logs and read the service.name on a new record. Ask the AI tool to filter on that name.
Only logs arrive. Many frameworks emit logs on their own but need explicit setup for metrics and traces. Ask the AI tool to add a trace for one request and a counter for one event, then run step 5 again.
The MCP server is not connected. Confirm the server in your AI tool first. In Claude Code, type /mcp. In Cursor, look for the green dot next to loggerhead.

See Tools reference for what each tool accepts.