Use
MCP analytics
If your site runs an MCP server, agents don't only read your pages: they connect to it and call your tools. Punchline records those calls the same way it records page views. You see which tools get called, by which agents and clients, and whether the work led anywhere.
This page is about your MCP server. To query Punchline itself from an agent, see MCP server.
What's recorded
Each POST to your MCP endpoint (Streamable HTTP) is stored as a visit by the agent that sent it, classified like any request. It shows up under its operator, such as OpenAI or Anthropic, when the network or a signature says who it is. Each JSON-RPC message in the request becomes one event:
| Message | Event | Kept |
|---|---|---|
initialize |
mcp_initialize |
the client's name and version, as it reports them (claude-ai 0.1.0) |
tools/call |
mcp_tools_call |
the tool name |
prompts/get |
mcp_prompts_get |
the prompt name |
anything else (tools/list, notifications/…) |
mcp_<method> |
nothing more |
Never recorded: tool arguments, results, resource URIs, or anything else from the message body. The body is read from a copy, so your MCP handler gets it unchanged. Bodies over 256 KB are skipped.
Each MCP request counts as one page view, as an agent fetching a page does.
Whether a call failed is known only when the install sees the response, which is the case with the Cloudflare Worker. The Next.js proxy runs before your handler, so there it records the call but not the outcome.
Set it up
Your edge install does it, version 0.4.0 or later. Any POST of JSON to a path ending in /mcp is picked up. If your endpoint is somewhere else, list it:
// proxy.ts (Next.js)
import { punchline } from "@punchline-analytics/next";
export const proxy = punchline({ mcpPaths: ["/api/agents/rpc"] });
export const config = {
matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"], // must include the MCP path
};
The Cloudflare Worker takes the same mcpPaths option.
Universal Commerce Protocol servers, like the catalog every Shopify store serves at /api/ucp/mcp, are picked up by the same rule. Each call there carries the agent's profile URL; from 0.6.0 Punchline keeps that URL's host name (chatgpt.com, say), which names the agent platform, and shows it as the client when the agent didn't send one. Nothing else from the call's arguments is kept: not the search, not the shopper's context. MCP's long-lived event streams (a GET with Accept: text/event-stream) are no longer counted as page views.
What you see
AI & agents → MCP:
- tool calls, agent sessions and failed calls
- each tool's calls and sessions
- who called: the operator and the client name the agent gave when it connected
- handoff links created in MCP sessions, and how many a person opened
The events are ordinary custom events, so you can also use them in goals, alerts and the API. For example, make mcp_tools_call with tool = create_quote a goal.
Handoff links from tools
When a tool builds something for the agent's person, such as a quote, a booking or a sandbox, return a handoff link in its result. Then the person who opens it is connected to the agent's MCP session. Put the receipt in the result text, so the agent knows which link to pass on:
// Inside your MCP server's create_quote tool (TypeScript MCP SDK)
server.registerTool("create_quote", { inputSchema: { plan: z.string(), seats: z.number() } }, async ({ plan, seats }, extra) => {
const quote = await saveQuote({ plan, seats });
// The HTTP request's headers, where your transport provides them (Streamable HTTP does).
const h = extra.requestInfo?.headers ?? {};
const ip = String(h["x-real-ip"] ?? h["x-forwarded-for"] ?? "").split(",")[0]!.trim(); // your host's client-IP header
const userAgent = String(h["user-agent"] ?? "");
const mcpSessionId = String(h["mcp-session-id"] ?? "");
const { data } = await punchline.createHandoff({
site_id: process.env.PUNCHLINE_SITE_ID!,
kind: "quote",
value: quote.total,
currency: "USD",
url: `/quote/${quote.id}`,
summary: `${quote.planName}, ${seats} seats`,
...(ip && userAgent ? { visitor: { ip, user_agent: userAgent, ...(mcpSessionId ? { mcp_session_id: mcpSessionId } : {}) } } : {}),
});
return { content: [{ type: "text", text: `Quote saved: $${quote.total}/month.\n\n${data.receipt_text}` }] };
});
Giving visitor (the MCP request's IP address and user agent, used in memory only) ties the link to the agent's MCP session, so Handoffs and the MCP report show the tool call that made it. Add mcp_session_id, the request's Mcp-Session-Id header, and the tie holds even when the agent's calls come from different addresses: the edge install records every call of one MCP session as one visit by that session (the id is hashed, never stored), and the mint finds the same visit.
Try it
The demo site, Acme Scheduling, has a small MCP server at https://agentlens-demo-eight.vercel.app/mcp with two tools, get_pricing and create_quote. create_quote saves a quote and returns a handoff link with its receipt. Connect it to Claude Code with:
claude mcp add --transport http acme-demo https://agentlens-demo-eight.vercel.app/mcp
Then ask for a quote for a 12-person team.
Privacy
The same rules as page views apply: an agent's IP address and user agent are kept only when it's on a hosting network or says or proves who it is. People don't call MCP servers directly, but if a request looks like a person's, nothing identifying is kept. Client names are what the client sends in initialize, cut to 60 characters.
Ask the docs
Answers come from these docs only, written by Claude (Anthropic). Your question is sent to answer it, and isn't stored.