Give your coding agent customer understanding: Atune over MCP in Claude Code and Cursor

Yes, your AI agent can query customer usage and health: Atune has an MCP server. Run npx atune mcp and Claude Code, Cursor or any MCP client gets an understand tool that answers questions about an account, a user, a feature or your whole customer base, with citations, and with knows: false instead of a guess when the evidence is thin.

Your coding agent knows your code. It doesn't know your customers: who is stuck in onboarding, which account went quiet last week, whether anyone uses the feature you're about to refactor. This guide sets Atune up in Claude Code and Cursor, shows what to ask, and explains how to read the answers.

You need a workspace with events flowing (see the Quickstart) and an API key. Atune is in a closed beta for software teams in the EU and EEA, so apply for access first.

What the agent getsCopy Anchor Link

The MCP server exposes understand() as a tool. The tool takes an entity and a question:

It returns the same result your own code would get:

type UnderstandResult = {
  knows: boolean;                 // false ⇒ "not enough understanding yet"
  answer: string;                 // plain language, grounded in your signals
  confidence: number;             // 0..1
  citations: { signal: string; value: string; when: string }[];
  recommendedNext: string | null; // one action, only when confident
  signals: Record<string, unknown>; // the structured grounding bundle (computed without an LLM)
};

The server uses your ATUNE_API_KEY and only sees your own workspace. It's the understand() surface exposed to an agent, nothing more.

Option A: local server with npx atune mcpCopy Anchor Link

The atune package ships a stdio MCP server:

npx atune mcp

It runs with a single understand tool, authenticated with ATUNE_API_KEY. You don't run it yourself; your MCP client starts it. See atune mcp.

Claude CodeCopy Anchor Link

Add it as a stdio server and pass the key as an environment variable:

claude mcp add atune --env ATUNE_API_KEY=$ATUNE_API_KEY -- npx atune mcp

Run this in your own terminal, in the same window where ATUNE_API_KEY is exported: the value is read when you add the server and saved in Claude Code's config. If the tool later says ATUNE_API_KEY is required, the variable was empty at that moment; remove the server, export the key and add it again. Don't paste the key into the chat with the agent.

Already have a server called atune, for example the hosted one below? Pick another name, such as atune-local.

Cursor and other MCP clientsCopy Anchor Link

Most clients take the standard mcpServers shape. In Cursor, put it in your global ~/.cursor/mcp.json, not in a project file you commit:

{"mcpServers": {  "atune": {    "command": "npx",    "args": ["atune", "mcp"],    "env": { "ATUNE_API_KEY": "<YOUR_API_KEY>" }  }}}

Ready-made config files for both editors, which read the key from your environment instead of a file, are in the mcp/ folder of atune-nextjs-example.

Your key is under Settings → API keys in Atune. It's the only secret; you can rotate it there if it leaks.

Option B: hosted MCP server for Claude Code and CodexCopy Anchor Link

Atune also runs a hosted MCP server at https://useatune.com/mcp, which you connect from Settings → AI agent in Atune. It gives Claude Code and Codex cited usage evidence and account health, and lets them run Atune's AI tasks on the subscription you already have. See Hosted MCP server for the commands, the tools and how to revoke access.

What to askCopy Anchor Link

Once connected, ask in plain language. The agent decides when to call the tool.

• "Which accounts look at risk this week?" (portfolio)
• "Why did Acme go quiet?" (account:acme)
• "Is anyone using the CSV import? I'm about to rewrite it." (feature:<key>)
• "Has Kari at Acme reached value yet?" (user:acme/u_123)
• "Before I change onboarding: which trials never got past setup?"

The most useful questions are tied to the code in front of you: who uses this feature, who would this change affect, which customer hit this error path.

How to read the answersCopy Anchor Link

Branch on knows. When there isn't enough understanding yet, Atune returns knows: false instead of guessing. A good agent reports it as "Atune doesn't have enough data on Acme yet", not as a made-up story.

Check the citations. Every answer cites the signals behind it: what was measured, the value, and when. If the agent's summary goes beyond the citations, trust the citations. Atune also checks every number in the answer against the signals; a number it can't back lowers the confidence and removes recommendedNext.

recommendedNext only appears when Atune is confident. It's one action, not a list.

knows: false on a new install usually means there isn't enough history yet. It doesn't tell you by itself whether capture is broken; check Settings → Event log in Atune.

You can make this explicit in your project's agent instructions (CLAUDE.md, AGENTS.md or Cursor rules):

## Customer questions
- Use the `atune` MCP tool for questions about customers, accounts, users or feature usage.
- If the result has `knows: false`, say Atune doesn't have enough data yet. Don't guess.
- Quote the citations (signal, value, when) when you summarise an answer.

Limits worth knowingCopy Anchor Link

• Daily answers. The free Build plan includes 20 new understand() answers per UTC day; a question repeated within the hour is served from cache. Paid plans are on the pricing page.
• Plan limit. If a free workspace goes past 25 active customer accounts, understand() and the MCP tool return 402 Insight locked with an upgrade link. Atune keeps receiving every event while locked. See Billing.
• It only knows what you send. Atune captures server-side behaviour (Next.js middleware, track(), the HTTP API, Segment or a PostHog import). No events, no understanding.
• Names need a DPA. Answers say "Kari at Acme" only if you send names with identify() and group() after accepting the data processing agreement; otherwise they use your IDs.

Why give an agent this at allCopy Anchor Link

An agent that can see customer behaviour makes different decisions: it can check whether a feature is used before deleting it, find which customers a bug touched, or draft a check-in for an account that went quiet. It can't invent the customer story: answers come from your signals, are cited, and say "I don't know" when they should.

NextCopy Anchor Link

• See capture, understand() and the MCP config together in one app: atune-nextjs-example.
• Not capturing yet? Add customer health to a Next.js app or Any backend.
• Reference: atune mcp, Hosted MCP server, understand(), Understanding & the Context Layer.