Connect an agent

This whole system is one MCP endpoint with two tools. Point an assistant at it and it can ask for feedback, record a score, and read the numbers back — in the conversation it is already having.

The endpoint

https://nps.cleartrust.cc/mcp

Authorise with Authorization: Bearer <token>, or let the client run the OAuth flow — this server is its own authorization server, and registers clients dynamically.

Claude Code, Claude Desktop, or anything that speaks MCP

claude mcp add --transport http feedback https://nps.cleartrust.cc/mcp

Or with a key you minted at your account:

claude mcp add --transport http feedback https://nps.cleartrust.cc/mcp \
  --header "Authorization: Bearer plk_..."

Or over stdio, as a subprocess

{
  "mcpServers": {
    "feedback": {
      "command": "node",
      "args": ["/path/to/headless-feedback/src/stdio.js"],
      "env": { "DATABASE_URL": "postgresql://…" }
    }
  }
}

The first three calls

// What is here, and how it fits together.
discover({ scope: "overview" })

// The fifteen calls that cover most of it.
discover({ scope: "examples" })

// Write down a score somebody just gave you.
execute({
  operation: "feedback.record",
  params: { email: "[email protected]", survey: "q3-nps",
            score: 9, comment: "Support fixed it in an hour." }
})

Things worth knowing before you build on it

You pass a raw score; the engine computes the segment. Writing a segment is refused.
Anywhere a person is wanted, an email address or crm:con_9f2 works as well as a per_ id.
dry_run: true runs an operation inside a transaction and rolls it back — always launch a survey that way first.
idempotency_key makes a retry safe: the same key returns the first result instead of asking somebody twice.
Errors name the field, the allowed values, or the operation you probably meant. Read them rather than guessing again.