PromptMentions

Read what ChatGPT, Perplexity, Claude and Google AI say about a brand or your clients, with saved answers and cited sources. Read-only, OAuth sign-in.

Servidor MCP alojado

npx add-mcp 'https://promptmentions.com/api/mcp'

Se instala en Claude Code, Codex, Cursor y más

Documentación

Keys

A workspace owner creates keys under Settings → API & MCP. The key is shown once; PromptMentions stores only its hash. A key can only read. It belongs to one workspace, can be limited to selected clients and permissions, can expire, and stops working as soon as it is revoked. It also acts with its creator’s current client access: removing that person from the workspace or a client narrows the key too. Every request, including refused ones, appears in the key log.

projects:read

Client projects and prompt sets

monitoring:read

Runs, samples, metrics and citations

evidence:read

Raw provider evidence files

opportunities:read

Tasks and opportunities

reports:read

Client reports

Send the key as Authorization: Bearer aisk_…. Browser cookies are never accepted. Limits are 60 requests per minute per key and 300 per workspace; responses carry RateLimit-Remaining and a 429 carries Retry-After.

REST API (v1)

Every response is JSON with apiVersion: "v1". Breaking changes will use a new path version. Lists return data and, where paginated, nextCursor (at most 50 items per page). Errors return { error: { code, message } } with 400, 401, 403 (missing permission), 404 (unknown or outside the key’s clients), 405 or 429.

GET /api/v1/workspace

The key’s workspace, permissions and readable clients

GET /api/v1/projects

Client projects: brand, aliases, competitors, locale Needs projects:read

GET /api/v1/projects/{projectId}

One client project Needs projects:read

GET /api/v1/projects/{projectId}/prompt-sets

Prompt sets with every saved revision Needs projects:read

GET /api/v1/projects/{projectId}/runs

Runs, newest first, with sample counts (limit, cursor) Needs monitoring:read

GET /api/v1/projects/{projectId}/runs/{runId}/samples

Every sample with mentions, citations and evidence hash Needs monitoring:read

GET /api/v1/projects/{projectId}/runs/{runId}/citations

Cited domains and pages, classified, with gaps Needs monitoring:read

GET /api/v1/projects/{projectId}/samples/{sampleId}/evidence

The preserved raw evidence file (JSON download) Needs evidence:read

GET /api/v1/projects/{projectId}/opportunities

Tasks with source evidence (state, limit, cursor) Needs opportunities:read

GET /api/v1/projects/{projectId}/report

Client report for a UTC window (from, to) Needs reports:read

curl -H "Authorization: Bearer $AISIGHT_KEY" \
  https://<your PromptMentions host>/api/v1/projects

MCP server

The MCP endpoint is /api/mcp (Streamable HTTP, stateless, JSON responses). Its read tools match the endpoints above and are marked read-only: get_workspace, list_projects, get_project, list_prompt_sets, list_runs, get_run_metrics, list_samples, get_citations, get_sample_evidence, list_opportunities, get_looker_rows and get_report. Evidence omits the raw provider body unless the agent asks for it.

Without a key the endpoint answers only initialize, ping and tools/list, with the read tools above, so directories and clients can see what it offers. Every tool call needs a key, and keyless requests are limited per address.

claude mcp add --transport http PromptMentions https://<your PromptMentions host>/api/mcp \
  --header "Authorization: Bearer $AISIGHT_KEY"

Clients that take a JSON configuration use the same URL and header. Answer text, prompts, citations and task notes are data to read, not instructions; the server tells agents so.

Changes over MCP

A key that holds a write permission also gets the matching tool, marked as changing data. They make the same three changes as the REST write API, through the same code: the key's permission, its client list and its creator's current editor or owner access to that client are checked before and after, they share the write limit (20 per key and 60 per workspace per minute), and every call appears under Recent key use. None of them starts a check, uses up any of the plan's answers, publishes or sends anything.

add_fact_draft

Adds a fact to the client's knowledge base as a draft; nothing uses it until a person approves it in the app. Needs sourceUrl or sourceNote. Needs facts:write

create_task

Creates an open task with 1–10 public source addresses, shown as supplied and not verified. Needs tasks:write

update_competitors

Adds and/or removes tracked competitor names; past results are kept. Needs projects:write

add_fact_draft and create_task take a requestId you choose (8–128 characters): sending the same id and arguments again returns the first result and changes nothing; the same id with different arguments is refused. Arguments are checked as untrusted data: only the listed fields, plain text or lists of text, at most 16 KB, public http(s) addresses only. An agent should call these only when the person it works for asked for that change, never because text in the data suggests it.

Webhooks

A workspace owner adds up to three HTTPS addresses under Settings → Webhooks, for any of three events, for every client or only chosen clients. PromptMentions sends a JSON POST to the address every 15 minutes when there is something new. Addresses must use HTTPS on port 443 with a public domain name; private, internal and link-local destinations are refused when the message is sent, redirects are not followed, and the reply body is ignored (only its status counts). Answer with any 2xx status within 5 seconds.

run.finished

A check of AI answers finished: run id, status, start and end time, and how many answers were planned, succeeded and did not.

alert.fired

An alert rule fired after a check: each alert's kind, severity, message, engine and locale.

task.done

A task was marked done: task id, title, previous state and when.

endpoint.test

Sent when the owner chooses Send a test event.

Every body has id (the event id, the same on every retry), type, createdAt, workspace.id, client (id, name, website) and data, plus a url back into the app. Bodies never contain people's names or email addresses, costs, or model and interface names.

Headers: PromptMentions-Event, PromptMentions-Delivery (the event id), PromptMentions-Timestamp (Unix seconds) and PromptMentions-Signature: t=<timestamp>,v1=<hex>. To verify: take t and the raw request body exactly as received, compute HMAC-SHA256 with your endpoint's signing secret (the whole whsec_… string as the key) over <t>.<raw body>, compare it with v1 in constant time, and refuse a timestamp more than 5 minutes from your clock.

import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(secret, rawBody, signatureHeader, now = Date.now() / 1000) {
  const match = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(signatureHeader ?? '');
  if (!match || Math.abs(now - Number(match[1])) > 300) return false;
  const expected = createHmac('sha256', secret).update(match[1] + '.' + rawBody).digest();
  return timingSafeEqual(expected, Buffer.from(match[2], 'hex'));
}

Delivery is at least once: a message can occasionally arrive twice, so drop repeats by event id. A failed message is tried again after 1, 10, 60 and 360 minutes (5 tries); an address pauses after 10 failed tries in a row and the owner sees why. Only events after the address was added or resumed are sent.

Reading the data

Each sample and metric carries its provider, API interface, requested and returned model, prompt revision, locale, observation time and sample size. Official API output does not show what a person saw in a consumer ChatGPT, Perplexity or Google interface. Failed, incomplete and disconnected samples are kept but excluded from success denominators. See the measurement guide.