Ratel Docs
Telemetry

Connect an MCP server

Send the tool calls your MCP server handles to Ratel Cloud, with a session and a user on each call.

Ratel Cloud reads the tool calls your MCP server handles. It groups them into sessions and runs, and finds the tasks your users do.

Your server sends one OpenTelemetry span per tool call. No Ratel SDK is needed.

What you need

  • A Ratel Cloud account. During the beta, you get one by invite.
  • A project API key. Create one in your project's Settings > API keys on cloud.ratel.sh.
  • Access to your MCP server's code. The server sends the spans, so it works with any client: Claude Code, ChatGPT, Cursor, and others.
SettingValue
Endpointhttps://cloud.ratel.sh/v1/traces
HeaderAuthorization: Bearer <your-key>
ProtocolOTLP over HTTP, http/protobuf or http/json

Keep the key on the server, for example in RATEL_API_KEY. Never put it in client config.

Send tool calls

The TypeScript MCP SDK makes no tool spans. You add one span around each tool handler.

Install

npm install @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-proto

Start the exporter

Import this file first, before the MCP SDK loads.

tracing.ts
import { NodeSDK } from "@opentelemetry/sdk-node";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";

const sdk = new NodeSDK({
  serviceName: "skill-router",
  traceExporter: new OTLPTraceExporter({
    url: "https://cloud.ratel.sh/v1/traces",
    headers: { Authorization: `Bearer ${process.env.RATEL_API_KEY}` },
  }),
});
sdk.start();

// Send the last spans before the process exits.
process.on("SIGTERM", () => sdk.shutdown().finally(() => process.exit(0)));

serviceName names your server in Ratel Cloud.

Add a span helper

tool-span.ts
import { SpanStatusCode, trace } from "@opentelemetry/api";
import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";

const tracer = trace.getTracer("skill-router");

export interface CallIds {
  sessionId?: string;
  userId?: string;
}

/** Runs one tool call inside an `execute_tool` span that Ratel Cloud reads. */
export function withToolSpan(
  toolName: string,
  ids: CallIds,
  run: () => Promise<CallToolResult>,
): Promise<CallToolResult> {
  return tracer.startActiveSpan(`execute_tool ${toolName}`, async (span) => {
    span.setAttribute("gen_ai.operation.name", "execute_tool");
    span.setAttribute("gen_ai.tool.name", toolName);
    if (ids.sessionId) span.setAttribute("session.id", ids.sessionId);
    if (ids.userId) span.setAttribute("user.id", ids.userId);
    try {
      const result = await run();
      if (result.isError) span.setStatus({ code: SpanStatusCode.ERROR });
      return result;
    } catch (error) {
      span.recordException(error as Error);
      span.setStatus({ code: SpanStatusCode.ERROR });
      throw error;
    } finally {
      span.end();
    }
  });
}

Wrap each tool

server.ts
import "./tracing.js";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";
import { withToolSpan } from "./tool-span.js";

const server = new McpServer({ name: "skill-router", version: "1.0.0" });

server.registerTool(
  "search_skills",
  { description: "Find skills that match a query.", inputSchema: { query: z.string() } },
  async ({ query }, extra) =>
    withToolSpan(
      "search_skills",
      { sessionId: extra.sessionId, userId: userIdOf(extra) },
      async () => {
        const skills = await searchSkills(query);
        return { content: [{ type: "text", text: JSON.stringify(skills) }] };
      },
    ),
);

extra.sessionId is the MCP session of a stateful HTTP server. userIdOf is your own lookup, for example from your auth.

FastMCP 4 and the MCP Python SDK 2.x make a tools/call span for each call. You only add the exporter.

Install

pip install fastmcp opentelemetry-sdk opentelemetry-exporter-otlp-proto-http

Start the exporter

Set the tracer provider before you import FastMCP.

server.py
import os

from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor

provider = TracerProvider(resource=Resource.create({"service.name": "skill-router"}))
provider.add_span_processor(
    BatchSpanProcessor(
        OTLPSpanExporter(
            endpoint="https://cloud.ratel.sh/v1/traces",
            headers={"Authorization": f"Bearer {os.environ['RATEL_API_KEY']}"},
        )
    )
)
trace.set_tracer_provider(provider)

from fastmcp import Context, FastMCP

mcp = FastMCP("skill-router")

service.name names your server in Ratel Cloud.

Add the session and the user

Inside a tool, the current span is the tools/call span. Set the ids on it.

server.py
@mcp.tool
def search_skills(query: str, ctx: Context) -> list[dict]:
    span = trace.get_current_span()
    span.set_attribute("session.id", ctx.session_id)
    span.set_attribute("user.id", user_id_of(ctx))
    return find_skills(query)

user_id_of is your own lookup, for example from your auth.

Prefer environment variables? The OTEL_EXPORTER_OTLP_TRACES_* variables in Send telemetry work too.

Sessions and users

Most MCP clients send no trace context. Each tool call then arrives as its own trace. Ratel Cloud uses the session id to put a user's calls back together.

AttributeWhat Ratel Cloud does with it
session.id or gen_ai.conversation.idGroups calls into one session. Splits the session into runs at gaps of 90 seconds.
mcp.session.idUsed when no session id above is set.
user.id or enduser.idShows patterns per user.
service.nameNames the server the calls came from.

Pick the session id in this order:

  1. The MCP session, when your server keeps one per client connection.
  2. Your own conversation id, when your server has one.
  3. The user id. A stateless server gets a new MCP session id on each request. Set session.id to the user id instead, and the 90-second gaps split each user's calls into runs.

Without a session id, each call is its own run, and no task can form.

Ratel Cloud does not read the client name (Claude Code, ChatGPT) yet.

Check it works

  1. Call a tool from any MCP client.
  2. Open Traces in your project. The Sessions tab shows one row per session id.
  3. Open the Spans tab. Each call shows as an execute_tool <name> or tools/call <name> span, under your service name.
  4. Open Agent health. The setup card shows Tool spans, Conversation id and User id as received.

Tasks appear in Agent health once enough runs with tool calls arrive.

An MCP server makes no model calls, so Model spans and Content stay not sent. That is expected. One trace per request also stays not sent when your client sends no trace context. The session id covers it.

What leaves your server

The spans on this page carry the tool name, timing, status, and the ids you set. They carry no tool arguments, results, or messages.

Ratel Cloud finds tasks from the order of tool calls. It needs no message content for that.

Troubleshooting

SymptomFix
401 from the endpointThe key is missing, wrong, or revoked. Check RATEL_API_KEY on the server.
No spans after a restartSpans are sent in batches. Shut the SDK down on exit, as in the examples.
Spans arrive, but no tool callsCheck that each span has gen_ai.operation.name set to execute_tool, or comes from FastMCP or the MCP Python SDK 2.x.
Every call is its own runSet session.id. See Sessions and users.
Runs mix several requestsRequests closer than 90 seconds on one session merge. Use a conversation id if you have one.

For status codes and limits, see Send telemetry.

On this page