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.
| Setting | Value |
|---|---|
| Endpoint | https://cloud.ratel.sh/v1/traces |
| Header | Authorization: Bearer <your-key> |
| Protocol | OTLP 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-protoStart the exporter
Import this file first, before the MCP SDK loads.
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
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
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-httpStart the exporter
Set the tracer provider before you import FastMCP.
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.
@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.
| Attribute | What Ratel Cloud does with it |
|---|---|
session.id or gen_ai.conversation.id | Groups calls into one session. Splits the session into runs at gaps of 90 seconds. |
mcp.session.id | Used when no session id above is set. |
user.id or enduser.id | Shows patterns per user. |
service.name | Names the server the calls came from. |
Pick the session id in this order:
- The MCP session, when your server keeps one per client connection.
- Your own conversation id, when your server has one.
- The user id. A stateless server gets a new MCP session id on each request. Set
session.idto 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
- Call a tool from any MCP client.
- Open Traces in your project. The Sessions tab shows one row per session id.
- Open the Spans tab. Each call shows as an
execute_tool <name>ortools/call <name>span, under your service name. - 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
| Symptom | Fix |
|---|---|
401 from the endpoint | The key is missing, wrong, or revoked. Check RATEL_API_KEY on the server. |
| No spans after a restart | Spans are sent in batches. Shut the SDK down on exit, as in the examples. |
| Spans arrive, but no tool calls | Check 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 run | Set session.id. See Sessions and users. |
| Runs mix several requests | Requests closer than 90 seconds on one session merge. Use a conversation id if you have one. |
For status codes and limits, see Send telemetry.
Related
- Send telemetry: the endpoint, headers, and what Cloud reads from model spans.
- Tool calls in imported runs: bring in past runs from PostHog, Langfuse, and others.