Helicone MCP server: two tools, 4,919 tokens

Helicone answers questions about LLM spend through two tools. Those two cost more context than OpenSearch's nine tools.

Last verified 1 September 2026 · from Helicone's documentation, the npm registry and the server's own tools/list response

This page is one of 90 in a directory of monitoring and developer tools. Each page checks what an AI coding agent can get out of the tool through its MCP server, the connector that lets the agent query the tool directly.

What is the Helicone MCP server?

It is Helicone's server for the Model Context Protocol. Helicone is a proxy and observability layer for LLM calls, so what the agent gains is a query interface over your own model traffic: which requests ran, what they cost, how long they took.

The surface is deliberately narrow. query_requests reads individual LLM calls and query_sessions reads grouped ones. There is no writing, no configuration, and no alerting.

The narrow surface is deliberate. It is also why the context cost is surprising. Both tools accept a rich filter object, and that filter is expressed in full in the tool's input schema.

Helicone covers AI cost management broadly, reaches part of the way into agent observability, and reaches nothing in code review, release or production observability.

For an agent, that means Helicone answers what your LLM calls cost and how they behaved, and nothing else. An agent connected here can tell you which model spent the most over a chosen window and which sessions ran slowest. It cannot tell you whether the output was any good, so this connector sits beside an evaluation tool rather than replacing one.

What can an AI agent do with Helicone?

What connecting costs before the first question

A context window is the amount of text a model can hold at once, and connecting uses some of it before the agent asks anything. Every tool the server registers sends its name, description and input schema to the model when the session starts. The tool list is charged whether or not a single tool is called.

Two tools here cost more than OpenSearch's nine. The descriptions are short, at 110 characters each. The input schemas average 10,074 characters per tool, the largest measured anywhere in this guide.

The reason is the filter. query_requests accepts a nested filter object that enumerates every filterable column against every operator. Every column gets one property for equals and one for not-equals. The pattern repeats across the whole request model. It is expressive, and the model pays for the whole grammar at connection whether or not it filters on anything.

Encodings: GPT-5.6, GPT-5.5 o200k_base; GPT-4, GPT-3.5 cl100k_base; Claude Haiku 4.5 to Opus 5 count_tokens. Counted 21 August 2026 from tools/list on the published @helicone/mcp package. It was run locally with a placeholder key.

Registration is static, so no Helicone account was involved. Figures cover name, description and input schema.

The two models in column one share the o200k_base encoding, so they get one count. The spread is formatting, about 38%. Reasoning tokens are output, spent per request. The tool list is input, charged once at connection.

The Claude figures are measured rather than encoded. Anthropic publishes no local tokenizer. So the definitions were sent to the API's count_tokens endpoint, and a no-tools baseline was subtracted. The range covers two tokenizer generations rather than two serializations. Haiku 4.5 and Opus 4.6 sit at the low end. Opus 5 and Sonnet 5 sit at the high end. The gap between them is about a third.

Can Helicone watch your own AI agents?

Helicone records model traffic, so the question is how much of that record two tools can reach. Counted from the server's own tools/list response on 21 August 2026.

Helicone MCP server limits: where answers come back incomplete

The limits below follow from a two-tool design rather than from anything failing.

How to configure Helicone MCP for agents

1. 1

   Connect it for a purpose, not permanently

   Two tools cost about 4,919 tokens, so the cost is disproportionate to the surface unless LLM spend is the question of the session.

2. 2

   Leave includeBodies off by default

   It returns full prompt and completion text, which is both your users' data and a large context cost.

3. 3

   Expect to filter by time explicitly

   The filter grammar is expressive and has no implied default window, so an unbounded query can be expensive on both ends.

4. 4

   Treat it as lightly maintained

   Version 0.1.6 was published on 4 November 2025 with nothing since.

Paste this into your agent’s instructions

Helicone answers exactly what the filter asked for, so the risk is an agent reporting a total from a narrow filter. The block makes the filter visible in the answer.

When you answer using Helicone MCP tools, state:
- The exact filter and time range you queried.
- How many records you retrieved against the limit you set.
  A full page is not evidence there are no more.
- Whether you requested bodies. Prompt and completion text is
  sensitive and should not be repeated without reason.
Never state that data does not exist. State that none was
returned under the constraints above.
Write your answer in ASD-STE100 Simplified Technical
English. Use short sentences with one idea in each.

Do you need the MCP server at all?

Often, yes. Helicone's REST API covers the same request and session queries with the same API key, and a coding agent can call it directly.

The connector's advantage is that an agent can discover the filter grammar from the schema rather than being told it. The schema that makes discovery possible is the schema that costs 10,074 characters. The benefit and the cost have one cause.

With two tools and a large schema, this is a connector to attach when LLM spend is the question of the session rather than one to leave permanently connected.

Connect it for a cost investigation. Call the REST API directly when the query is fixed and you want the context back.

Helicone MCP server setup

The package runs with npx and needs a Helicone API key in HELICONE_API_KEY. There is nothing else to configure.

claude mcp add-json "helicone" '{"command":"npx",
  "args":["-y","@helicone/mcp"],
  "env":{"HELICONE_API_KEY":"<your-key>"}}'

{"mcpServers":{"helicone":{"command":"npx",
  "args":["-y","@helicone/mcp"],
  "env":{"HELICONE_API_KEY":"<your-key>"}}}}

[mcp_servers.helicone]
command = "npx"
args = ["-y", "@helicone/mcp"]
env = { HELICONE_API_KEY = "<your-key>" }

Every other client

Each block below is the configuration for one client, with the file path and the key that client expects.

{"mcpServers":{"helicone":{"command":"npx",
  "args":["-y","@helicone/mcp"],
  "env":{"HELICONE_API_KEY":"<your-key>"}}}}

{"mcpServers":{"helicone":{"command":"npx",
  "args":["-y","@helicone/mcp"],
  "env":{"HELICONE_API_KEY":"<your-key>"}}}}

{"servers":{"helicone":{"command":"npx",
  "args":["-y","@helicone/mcp"],
  "env":{"HELICONE_API_KEY":"<your-key>"}}}}

{"mcpServers":{"helicone":{"command":"npx",
  "args":["-y","@helicone/mcp"],
  "env":{"HELICONE_API_KEY":"<your-key>"}}}}

Read-only access, permissions and security

• Both tools read

  There is nothing here that writes, which makes this one of the few connectors that is read-only by construction.

• includeBodies exposes prompt and completion text

  That is your users' input and your model's output, pulled into the agent's conversation and into whatever logs that conversation touches.

• The key carries your Helicone access

  It reaches the traffic your organization proxies, so scope it as you would any observability credential.

• Lightly maintained

  No release since 4 November 2025, so plan on the current behavior rather than on fixes.

Troubleshooting

No sessions found

query_sessions reads groupings that exist only when your integration sets a session identifier. Without one there is nothing to group.

Two tools cost more context than expected

It is. The input schemas average 10,074 characters because the filter grammar is expanded inline. Connect it for a cost investigation rather than leaving it attached.

401 on connect

HELICONE_API_KEY is missing or belongs to another organization.

The agent pulled full prompts into the chat

includeBodies was set on query_requests. Leave it off unless the filter is already narrow and you need the text.

Helicone MCP server: Reference

What engineers report

Helicone's MCP server has a small public footprint, so this section reports counts rather than quotes.

Package facts from the npm registry, retrieved 21 August 2026. Tool counts, description lengths and schema sizes come from the server's own tools/list response.

Should you connect an agent to Helicone?

Yes, though it is no longer actively maintained. Best for short, deliberate cost investigations rather than a permanently connected server.

Strongest fit

Teams already proxying LLM traffic through Helicone who want an agent answering cost and latency questions in the editor.

Main advantage

A precise filter grammar over your own model traffic, discoverable by the agent without documentation.

Main weakness

Two tools cost about 4,919 tokens, and the surface reads only requests and sessions.

Operational risk

includeBodies pulls full prompt and response text into the conversation.

Frequently asked questions