Agent Feedback

AI agents such as Claude Code, Cursor and ChatGPT increasingly use your product through your MCP server. Agent Feedback gives those agents a submit_feedback tool inside your server, and gives you an inbox in the Notra dashboard to triage what comes in.

How it works

Copy your feedback URL from the Feedback page in your dashboard (in the GEO sidebar under Visibility).
Register the feedback tool in your MCP server with @usenotra/geo/feedback, or POST to the URL from your own tool implementation.
Feedback shows up in the Feedback inbox, where you can filter by status and kind and mark items as triaged, resolved or archived.

Your feedback URL

Every organization has its own feedback URL:

https://api.usenotra.com/v1/feedback/{organizationSlug}

It needs no token or API key, so it can live directly in your server code. Submissions are rate limited per source IP and per organization (see Rate limits). Reading and triaging feedback through the API requires an API key with feedback.read or feedback.write. POST /v1/feedback (without a slug) also accepts an API key with feedback.write for server-side integrations that already hold one.

Add the tool to your MCP server

npm install @usenotra/geo

server.ts

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { registerFeedbackTool } from "@usenotra/geo/feedback";

const server = new McpServer({ name: "acme", version: "1.0.0" });

registerFeedbackTool(server, {
  url: "https://api.usenotra.com/v1/feedback/acme",
  productName: "Acme",
});

registerFeedbackTool adds a submit_feedback tool that accepts message, title, kind, sentiment and contextUrl, posts it to Notra and returns a short confirmation the agent can relay to the user (“Thanks, the feedback was sent to the team.” or “This feedback was already recorded.”). Options:

Option	Notes
`url`	Your feedback URL. Required.
`productName`	Used in the tool description so agents know what the feedback is about.
`toolName`, `description`	Override the default name and description.
`defaults`	Values merged into every submission. Accepts `agentClient`, `agentModel`, `toolVersion`, `projectId` and `metadata`, for example `{ agentClient: "acme-mcp" }`.
`fetch`, `timeoutMs`	Transport overrides for tests and custom runtimes. The default timeout is 10 seconds.
`onError`	Called with the error when a submission fails. The tool still returns an `isError` result to the agent.

The package also exports createFeedbackToolHandler(options) and feedbackToolInputSchema if you register tools yourself, and submitFeedback(input, { url }) for use outside MCP. submitFeedback posts a single entry and resolves with { id, deduplicated }; failures throw a FeedbackSubmitError with a status property.

REST endpoint

curl -X POST https://api.usenotra.com/v1/feedback/acme \
  -H "Content-Type: application/json" \
  -d '{
    "message": "The search tool times out when the query has quotes.",
    "contextUrl": "https://docs.example.com/api/search"
  }'

The endpoint returns 202 Accepted with the stored entry:

{
  "feedback": {
    "id": "fb_123",
    "projectId": null,
    "source": "api",
    "kind": "bug",
    "sentiment": "negative",
    "status": "new",
    "title": "Search tool times out on quoted queries",
    "message": "The search tool times out when the query has quotes.",
    "agentClient": null,
    "agentModel": null,
    "toolVersion": null,
    "userAgent": "curl/8.7.1",
    "contextUrl": "https://docs.example.com/api/search",
    "externalId": null,
    "idempotencyKey": null,
    "metadata": null,
    "resolvedAt": null,
    "createdAt": "2026-09-02T10:00:00.000Z",
    "updatedAt": "2026-09-02T10:00:00.000Z"
  },
  "deduplicated": false
}

Pass an idempotencyKey to make retries safe: submitting the same key twice for the same organization returns the original entry with deduplicated: true. An unknown organization slug returns 404.

Automatic classification

Only message is required. When title, kind or sentiment are omitted, Notra fills them in with a small model before storing the feedback, so the inbox stays readable and filterable even if the agent only sends free text. Values you pass explicitly are always kept. Classification runs through the same model gateway as the rest of Notra, so your organization’s zero data retention setting applies to it. If classification fails or no eligible model is available, the feedback is still stored, with kind: "other" and no title or sentiment.

Fields

Field	Required	Notes
`message`	yes	Up to 4000 characters.
`title`	no	Short summary, up to 200 characters. Written automatically when omitted.
`kind`	no	`bug`, `feature`, `praise`, `question` or `other`. Classified automatically when omitted.
`sentiment`	no	`negative`, `neutral` or `positive`. Classified automatically when omitted.
`source`	no	`mcp`, `api` or `sdk`. Defaults to `api`. Set it if you want to tell channels apart in the inbox.
`agentClient`, `agentModel`, `toolVersion`	no	Identify the agent that submitted the feedback. Up to 200 characters each.
`userAgent`	no	Up to 2048 characters. Defaults to the request’s `User-Agent` header.
`contextUrl`	no	The page or resource the feedback is about. Must be a valid URL, up to 2048 characters.
`externalId`	no	Your own identifier for the user or session, up to 200 characters.
`idempotencyKey`	no	Up to 200 characters. Deduplicates retries per organization.
`projectId`	no	File the feedback under one of your GEO projects. Returns `404` if the project does not belong to the organization.
`metadata`	no	Arbitrary JSON object, up to 8 KB.

Read and triage feedback

With an API key that has feedback.read, list entries with optional status, kind and projectId filters. Results are newest first and paginate with page and limit (default 25, max 100). See Pagination.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.usenotra.com/v1/feedback?status=new&kind=bug&limit=50"

{
  "feedback": [ { "id": "fb_123", "status": "new", "kind": "bug", "...": "..." } ],
  "pagination": {
    "limit": 50,
    "currentPage": 1,
    "nextPage": null,
    "previousPage": null,
    "totalPages": 1,
    "totalItems": 1
  }
}

GET /v1/feedback/{feedbackId} returns one entry as { "feedback": ... }. To move an item through triage, PATCH /v1/feedback/{feedbackId} with feedback.write and a status of new, triaged, resolved or archived. Setting resolved stamps resolvedAt.

curl -X PATCH "https://api.usenotra.com/v1/feedback/fb_123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "resolved" }'

Rate limits

Submissions to your feedback URL are limited to 30 requests per 10 minutes per IP address and 200 requests per hour per organization. Because your MCP server is the one posting, a hosted server that serves many users from a single IP shares the IP budget; local (stdio) servers get a budget per user machine. POST /v1/feedback with an API key is limited to 120 requests per minute per key instead. Responses include the standard RateLimit-* headers described in Rate limits.

Getting Started

Guides

Webhooks

Endpoints

How it works

Your feedback URL

Add the tool to your MCP server

REST endpoint

Automatic classification

Fields

Read and triage feedback

Rate limits

​How it works

​Your feedback URL

​Add the tool to your MCP server

​REST endpoint

​Automatic classification

​Fields

​Read and triage feedback

​Rate limits

How it works

Your feedback URL

Add the tool to your MCP server

REST endpoint

Automatic classification

Fields

Read and triage feedback

Rate limits