Start tracing AI agents free: Setup in 5 minutes

To start tracing AI agents free, sign up at mcpd.sh/app, create a project and set OTEL_EXPORTER_OTLP_ENDPOINT=https://api.mcpd.sh and OTEL_EXPORTER_OTLP_PROTOCOL=http/json with that project’s API key. Run your agent: each model call, tool call and retrieval appears with its prompt, answer and cost. Any framework, language or provider works, and you don’t need a vendor package.

A refund agent that worked on your laptop calls the same tool again and again in production. Or the model bill spikes overnight, and the logs don’t say which run caused it.

With a first trace sent from your own code, you can go from either symptom to one run, one span inside it and the payload that explains it: the prompt the model received, the completion it returned and what the step cost.

Key Takeaways

• mcpd is not a gateway or proxy, so recording a span never blocks or throws, and a slow daemon can’t slow your agent.
• An unknown model has no cost, not a cost of zero, so a missing price never reads as free.
• A W3C traceparent header is vendor-neutral and keeps an agent across API, queue and worker as one trace.
• Redaction runs before the write, so a masked secret was never stored.

How do you start tracing AI agents free in five minutes?

You start tracing AI agents free by pointing the agent’s OpenTelemetry exporter at https://api.mcpd.sh with a project key. It takes about five minutes and adds no package to the agent.

1. Sign up at mcpd.sh/app.
2. Create a project and copy its key. Store it in your secret manager or an untracked .env file, never in the repository.
3. Export the exporter variables in the shell or service environment that launches the agent:

export OTEL_EXPORTER_OTLP_ENDPOINT=https://api.mcpd.sh
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json
# add the project key exactly as https://mcpd.sh/docs/opentelemetry shows

The OpenTelemetry exporter specification defines both variables, and http/json is one of its protocol values next to http/protobuf. Place the project key where mcpd’s OpenTelemetry documentation says to place it.

4. Run the agent as you normally do. Exporters read these variables at startup, so restart a process that was already running, and set them in the same terminal or service unit that launches it.
5. Open the run in the interface at mcpd.sh/app, inside your project. The newest run is at the top.

What you see when you start tracing AI agents free

When you start tracing AI agents free, the first trace is a tree: one root span for the run, with each model call, tool call and retrieval nested beneath it in the order they ran.

mcpd’s home page puts it as “A run is a tree of model calls, tool calls and retrievals.” Opening a step shows its prompt, its answer, its tokens and its cost.

A refund agent that calls a lookup tool twice and then the model once produces a root span with two tool spans and a model span beneath it.

Why you can start tracing AI agents free with no SDK

You can start tracing AI agents free without an SDK because OpenTelemetry exporters read the same two environment variables in every language.

The setup applies whatever you build with, as long as the instrumentation emits OTLP:

• Frameworks: LangChain, LangGraph, LlamaIndex, CrewAI, the Vercel AI SDK, the OpenAI Agents SDK or Pydantic AI.
• Model providers: OpenAI, Anthropic, Google Gemini, Mistral, Azure OpenAI, Groq, Ollama or vLLM.

mcpd runs as a daemon beside the agent, so there is no framework to build on. Its SDKs are optional convenience over a plain HTTP API, and the integration guide shows when to use them.

Start free at mcpd.sh/app and send your first run.

Where can you start tracing AI agents free?

Free covers every feature on all three routes (the hosted version, the OTLP endpoint and a source build), with no paid plan and no feature behind a gate.

The hosted version at mcpd.sh/app is the full product. Its ingest address is the OTLP endpoint https://api.mcpd.sh, so any exporter in any language reaches it with OTEL_EXPORTER_OTLP_ENDPOINT and a project key.

To build from source with Rust and Node installed:

• make build compiles the binary, with the interface compiled into it.
• make dist produces the optimised build.

Then run ./target/release/mcpd demo and open http://localhost:4317. The code is at github.com/loruorg/mcpd.

Hosted and self-hosted are the same product: one static Rust binary that serves a laptop and a team cluster. These are configuration on that binary:

• accounts and roles
• single sign-on
• quotas
• an audit log

A team points the binary at Postgres or ClickHouse instead of the SQLite file. The operations guide covers running it.

You can leave without a migration. The mcpd README says, “What it stores it also forwards, as OTLP, to any endpoint you name.” Moving data elsewhere is an OTLP setting.

The code is under the Apache-2.0 licence.

• For a first trace today, with nothing to run, use the hosted version.
• If an agent already exports OpenTelemetry, change one address to the OTLP endpoint.
• A laptop, an air-gapped machine or a team that wants the data on its own storage fits the source build.

What does a trace of an AI agent contain?

A trace of an AI agent is the record of one run: a tree of spans, one per model call, tool call and retrieval, each with its prompt, completion, token counts, latency and cost. mcpd builds it from OpenTelemetry gen_ai.* and OpenInference llm.* attributes, so existing instrumentation works without changes.

When users report that a refund agent never finishes, filter for the slow runs and open one in the runs view. The waterfall shows a root span for the whole run, with model, tool and retrieval spans nested under it.

In a looping run the same lookup tool span repeats.

agent run (root span)
  model call   prompt, completion, tokens, latency, cost
  tool call    lookup_order
  model call
  tool call    lookup_order
  retrieval    refund policy

Open the last model span and read its payload. The prompt holds the tool result, and the completion asks for the same lookup again.

The mcpd home page says “Search finds a run by what the model said”, so you can search for the phrase the agent repeats instead of relying on labels alone.

The mcpd docs state that “A score is what a machine thought. Feedback is what a person thought.” They stay separate signals and are never averaged into one number.

Scores and feedback join the run’s spans, logs, metrics and aspect notes by run. The concepts page defines each signal.

How do you keep an agent spanning API, queue and worker in one trace?

An agent stays in one trace across an API, a queue and a worker when every hop passes the W3C traceparent header along, so each new span is created as a child of the span that called it.

The W3C Trace Context Recommendation defines the header as four fields joined by hyphens, and gives this example: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01.

Read left to right, that is the version (00), the trace id, the parent id and the trace flags (01). The trace id names the whole run. The parent id names the span that made the call.

A queue has no HTTP request to carry the header, so you put it in the message:

# API side: store the current context in the job
MSG=$(jq -n --arg tp "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01" \
  '{job:"refund", order:"A-1042", traceparent:$tp}')

# Worker side: read it back before starting any span
echo "$MSG" | jq -r .traceparent

In an OpenTelemetry-instrumented worker, the propagator extracts that value and starts its span with the same trace id and the enqueuing span as parent.

Without the header, the worker starts a new trace. Braintrust’s article on distributed tracing says that when context is lost at a service boundary, a failed tool call or slow background job can appear in a separate trace.

The refund run then becomes two fragments, and nothing links the failed tool call to the request that caused it.

mcpd reads W3C traceparent, so any OpenTelemetry-instrumented service joins the same trace with no vendor SDK. Logs and metrics carry the same trace id, so they join the run too. The OpenTelemetry ingestion guide covers the exporter settings.

What controls make tracing AI agents safe in production?

Tracing AI agents is safe in production when each control decides what gets written, how much, for how long, who can read it and what happens to the agent if the tracer fails. mcpd sets every one of them in configuration, and its security documentation covers them for a team deployment.

1. Redaction runs before storage, on every signal, with four modes: drop removes the value, mask replaces it, partial keeps a few characters, and keyed hash swaps it for a hash that still lets you match equal values. mcpd’s privacy docs give the reason: “Redaction runs before the write, because a secret deleted afterwards was still written down.” Without it, an API key pasted into a prompt lives on in the database, its backups and its exports.

2. Sampling decides which runs are kept, with five modes: always, never, ratio, deterministic and tail. Tail sampling decides once a run is complete, so it can keep the failing and slow runs that a random ratio would drop. Without sampling, a busy agent stores every payload whether anyone will read it or not.

3. Retention is set in days, and data older than that is removed. An erasure request about a person removes what is stored about them. Without both, prompts containing personal data pile up indefinitely and a deletion request has no answer.

4. API keys carry six scopes: ingest, read, write, execute, worker and admin. With no keys set, ingest and reads are open, which is for a laptop only. Give an exporter a key with the ingest scope and a leaked agent credential can’t read prompts back.

5. Forwarding goes only where you send it. The only route out is an endpoint you configured, and redaction has already run by the time data reaches it.

Why a failed tracer can’t break the agent

The mcpd README is direct: “It is not a gateway and not a proxy. Nothing travels through mcpd to reach a model, so mcpd being slow or down cannot slow your agent or break it.” Your agent calls the model provider directly, and mcpd only receives a copy of what happened.

Recording a span never blocks, never throws and never grows without bound. If mcpd is unreachable, the agent doesn’t notice.

How does cost per step work, and what happens for an unknown model?

mcpd prices every step as its span arrives, so a cost spike on a bill or a chart traces back to one step, and a model it can’t price gets no cost at all.

Cost is priced once, at ingest, per step, from a price book of per-million-token rates. The book handles cached tokens, long-prompt tiers and service tiers.

The price is written when the span lands, so history doesn’t change when rates change later.

If a span names a model the price book doesn’t list, the step carries no cost, so a missing price never hides as a free call. You can supply your own price book for the models you name yourself.

When the cost monitor fires, open the project that jumped, then the model, then the most expensive run, and read the step whose token usage grew.

A looping agent repeats the same tool step while the prompt gets longer on each model call.

For a limit on each run, the cost_budget scorer is one of the deterministic scorers covered in the testing guide. It never calls a model.

The cost monitor watches the total across runs. mcpd evaluates monitors every 60 seconds, on error_rate, latency_p95, cost, score_mean, trace_count and step-count divergence.

A monitor latches and fires once, so a spike that lasts an hour gives you one notification, not 60. It calls your webhook when it fires.

A monitor resolves only on a real reading. Silence is not recovery: if the agent stops sending traces, the monitor can’t read a healthy value, so it doesn’t declare the problem over.

Frequently asked questions

How do I start tracing AI agents for free?

Sign up at mcpd.sh/app, create a project key, and set the two exporter variables in your agent’s environment. Add the key as mcpd’s OpenTelemetry documentation shows. Run the agent once and the trace appears in your project, with no package installed.

Do I need an SDK or to change my framework?

You need no SDK and no framework change. Any agent that already exports OpenTelemetry spans sends them to mcpd once its exporter reads those two environment variables. Spans that carry gen_ai.* attributes show up as model calls, and mcpd’s OpenTelemetry guide lists the supported conventions.

Can mcpd slow down or break my agent?

It can’t, because mcpd sits beside your agent, not in front of it. As the mcpd README states, if the daemon is slow or down, your agent’s model calls run the same way.

Is my prompt data sent anywhere by default?

Your agent sends spans only to the address in OTEL_EXPORTER_OTLP_ENDPOINT. Set it to https://api.mcpd.sh and the spans, prompts included, go to your project there. Build from source at github.com/loruorg/mcpd and point the exporter at your own machine to keep them local.

Can I move my traces to another tool later?

Yes. mcpd forwards what it stores as OTLP to any endpoint you name, so another OpenTelemetry-compatible tool can receive the same spans. Your agent’s instrumentation doesn’t change, because it only ever spoke OpenTelemetry.

What to do in your first five minutes, first hour and first week

You can start tracing AI agents free in one sitting, then add depth as the agent earns more of your attention.

• In the first five minutes, sign up at mcpd.sh/app, set OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_EXPORTER_OTLP_PROTOCOL with your project key, run the agent once and open the first run.
• In the first hour, search for a failing run by a phrase the model said and read the payload of the span where it went wrong. Set a redaction mode before real user data arrives.
• In the first week, add a cost monitor so a spike points to its run, and a deterministic scorer that catches a looping tool call. Pass traceparent through your queue so the worker’s spans join the same trace as the API request.

The way you start tracing AI agents free adds no package to your agent, so removing the two variables undoes it. The quickstart walks through the first run in more detail.

Sources

mcpd.sh · mcpd README · Cost · mcpd · Tracking distributed tracing for AI agents: how to follow… · Privacy · mcpd · OpenTelemetry · mcpd · Evaluation · mcpd · Alerting · mcpd. Every other source is linked where the article cites it.