Add a feedback tool to your MCP server

Agents that use your MCP server already know when something does not work: a tool is missing, returns the wrong thing, or needs arguments they cannot guess. Agentback adds a send_feedback tool to your server so they can tell you, and you read every report in one inbox.

Install

sh
npm install agentback

The integration needs Node.js 20 or later (Deno, Bun and edge runtimes work too), @modelcontextprotocol/sdk 1.23+ or @modelcontextprotocol/server 2.x, and zod 4.2+, which an MCP server usually has already.

Add the feedback tool

Add this where the server registers its other tools. If the server is created per session or per request, add it in the same place so every instance gets the tool.

ts
import { Agentback } from 'agentback';
import { attachToMcp } from 'agentback/mcp';
const agentback = new Agentback({ projectKey: 'af_...' });
// Registers a send_feedback tool whose description tells agents when to use it.
attachToMcp(server, agentback, { product: 'Your product' });

server is your McpServer instance and product is your product's name, which the tool description uses.

Pick the right key

The server runs on users' machines (stdio, installed with npx and similar): use the project key. It can only submit reports, so it is safe to publish.
The server runs on your own infrastructure (Streamable HTTP or SSE): use the secret key from an environment variable. It lets the server attach the signed-in account.

ts
const agentback = new Agentback({
  secretKey: process.env.AGENTBACK_SECRET_KEY,
});
attachToMcp(server, agentback, {
  product: 'Your product',
  identify: () => ({ account: session.accountId }),
});

What agents send

The tool asks agents how their task ended, which is required:

Outcome	Meaning
`blocked`	The agent could not finish
`worked_around`	It finished another way
`friction`	It finished, but only after retries or guessing

Agents can also name the tool that had the problem, say what they were trying to do, what they expected and what happened instead, and suggest what would have helped. Each report records source mcp, the MCP client's name and version, and your server's version from the McpServer constructor (pass version to override it).

Tool names that agents copy with a client prefix, such as mcp__yourserver__search, are stored as search, so reports about one tool group together. If your server already has a tool called send_feedback, pass toolName to choose another name.

Test it

Run the server and call send_feedback from the MCP Inspector, or ask a connected agent to do something your tools cannot do. It should report the gap before it finishes. A stored report returns { "id": "fb_...", "status": "new" } and appears in your inbox.

Failed reports never break the agent's task: the tool tells the agent the report was not sent and not to retry.

Hand the setup to your coding agent

Paste one prompt into Claude Code, Cursor or Codex. It finds your MCP server, CLI, API or web app, connects to your account and adds Agentback.

Create a free inbox

Overview CLI