---
title: "Menciona for Agents — MCP & agent API"
description: "AI agents can autonomously register, subscribe, and query brand AI-visibility data via the ACP atomic checkout flow."
lang: en-US
---
# Your AI visibility, built for agents

Point any MCP-compatible agent at Menciona to query or fix your brand's AI-visibility data. Agents can register and subscribe autonomously via the ACP atomic checkout — no human required.

## What agents can pull

Every metric in the dashboard, available programmatically.

- **Brand visibility** — Mention rate and sentiment across ChatGPT, Claude, Gemini, Perplexity and more.
- **Competitors** — Side-by-side visibility and trends against the brands you compete with.
- **Tracked prompts** — The real questions buyers ask AIs: listed, created, and updated.
- **Sources & community** — Which domains and discussions drive your citations.
- **Audits & fixes** — Site audit scores, failing checks, and a ranked list of what to fix first.

## The atomic agent pipeline

One POST to `/complete` atomically creates the account, subscribes, and returns a long-lived API key — register and pay in a single call, no human required.

### 1. Discover

Read `/auth.md`, the `agent_auth` block at `https://api.menciona.ai/.well-known/oauth-authorization-server`, or the ACP feed at `https://app.menciona.ai/api/acp/feed` to find available plans and the checkout entry point. The feed also returns a `publishable_key` (`pk_…`, safe to use client-side) needed for the next step. Each offer carries an `includes` block — `monitoring_prompts`, `audited_websites`, `audit_runs_per_month`, `projects` — so you can choose a plan on substance, not just price. The api-catalog at `/.well-known/api-catalog` provides a machine-readable anchor to all ACP surfaces.

### 2. Tokenize the card

Use the `publishable_key` from the feed to create a reusable Stripe PaymentMethod. The raw card goes to Stripe, never to Menciona. `allow_redisplay=always` is required so the card can be reused for renewals.

```bash
curl https://api.stripe.com/v1/payment_methods \
  -u "$PUBLISHABLE_KEY:" \
  -d type=card \
  -d "card[number]=4242424242424242" \
  -d "card[exp_month]=12" -d "card[exp_year]=2030" -d "card[cvc]=123" \
  -d allow_redisplay=always
# → { "id": "pm_…", ... }
```

### 3. Open a checkout session

```http
POST https://app.menciona.ai/api/acp/checkout_sessions
Content-Type: application/json

{ "plan_price_id": "<from the feed>" }
```

Response: a `CheckoutSession` object with `id` (`cs_…`).

### 4. Complete (register + pay — atomic)

```http
POST https://app.menciona.ai/api/acp/checkout_sessions/{id}/complete
Content-Type: application/json

{
  "buyer":        { "email": "agent@example.com" },
  "payment_data": { "token": "pm_…", "provider": "stripe" },
  "consent":      { "recurring": true }
}
```

Success response — a long-lived API key issued atomically by this single call:

```json
{
  "workspace_id":    "…",
  "subscription_id": "sub_…",
  "access_token":    "menciona_…",
  "token_type":      "Bearer"
}
```

> Cards that require 3D Secure (mostly EU/UK) cannot complete headlessly — the call returns `requires_3ds`; retry with a different card. An email that already has a Menciona workspace returns `409 requires_sign_in` — use a different email for a fresh anonymous workspace, or sign in at app.menciona.ai.

**Email model:** Use a real address so a human can reclaim the workspace via password reset on app.menciona.ai. Use any other address for a fully anonymous account. Choose based on your operational needs.

**Credential type:** The `access_token` is a **long-lived API key** (prefix `menciona_`), not an OAuth token. There is no `expires_in` and no `refresh_token` — the key is valid indefinitely until revoked (Spike 0.2 decision B).

**Recurrence note:** The `consent.recurring: true` field authorizes the reusable payment mandate created during checkout. Subscription renewals are handled server-side; the agent does not need to re-authorize each billing cycle.

### 5. Operate

Add the key as a bearer token on every request:

```
Authorization: Bearer menciona_…
```

Use the key with the MCP server (`https://api.menciona.ai/mcp`). Renewals are managed server-side — no refresh loop needed. If you drive the server over raw HTTP, send an `initialize` request, then `tools/list` to discover every tool (including `feedback.submit` for reporting issues), then `tools/call` — the full JSON-RPC handshake is in the [MCP guide](/en/mcp/).

### 6. When prompts & audits run (and quota)

Creating a project triggers its first site audit immediately, and creating a prompt triggers its first run immediately; both then run on a **daily schedule**. The work runs in the background and is not instant — usually ready within a few minutes (allow up to ~15 for a large site) — so **poll** rather than assuming an empty result means "no data":

- **Site audit** — poll `audits.list` / `audits.get` until the audit's `status` is `done` (the terminal success status; an audit that finished with some check errors is also reported as `done`). An empty `audits.list` right after creating a project means *not ready yet*, not *no audit*.
- **Prompt results** — brand-visibility and competitor metrics populate once the run completes (`brand_visibility.get` / `sources.get`). `no_runs_yet` means check back shortly, not that the brand has no coverage.

**Quota gating:** prompts and audits only execute while the account is within its plan quota. Prompts stop running for the day once the **daily prompt limit** (`includes.monitoring_prompts`) is reached; audits only run for projects within the plan's **audited-website slots** (`includes.audited_websites`) and only while **monthly audit-run credits** (`includes.audit_runs_per_month`) remain. Choose a plan whose `includes` cover your needs.

## Let your agent fix it in your repo

Menciona doesn't just report problems. Open your coding agent inside your website's repository, connect the Menciona MCP, and tell it to work the audit. It reads what's failing and edits the files (schema, metadata, structure) that make AI engines cite you.

1. **Open your agent in the repo** — Claude Code, Cursor, Copilot, whatever your team already uses, in your site's codebase.
2. **Connect the Menciona MCP** — One config line, and your agent can read your audits, scores, and ranked fixes.
3. **Tell it to work the audit** — It pulls the failing checks and edits the files to fix them, then you review the diff.

You say: *"Connect to Menciona, pull my latest site audit, and fix the open issues in this repo."*

## Connect in two calls

Point any MCP client at the Menciona server, or register and subscribe autonomously via the ACP checkout flow. Discover available plans at `/auth.md`, the `agent_auth` block, the api-catalog, or the ACP feed.

```json
{
  "mcpServers": {
    "menciona": {
      "url": "https://api.menciona.ai/mcp",
      "headers": {
        "Authorization": "Bearer menciona_…"
      }
    }
  }
}
```

## Discoverable by design

Agents and LLMs can read how to work with Menciona from machine-readable manifests served at the root domain.

- `/auth.md` — Agent registration recipe
- `https://api.menciona.ai/.well-known/oauth-authorization-server` — agent_auth block (on the API host)
- `/.well-known/api-catalog` — API catalog (RFC 9727)
- `https://app.menciona.ai/api/acp/feed` — ACP product feed (USD; served from the app host, not the root domain)
- `/.well-known/agent-skills/index.json` — Skills manifest
- `/.well-known/mcp/server-card.json` — MCP server card
- `/.well-known/openapi.json` — ACP checkout OpenAPI spec
- `/llms.txt` — Site map for LLMs

### Agent skill docs

- `/skills/how-monitoring-and-audits-work.md` — Lifecycle: cadence, triggers, polling
- `/skills/quotas-and-limits.md` — Plan quotas: prompt-run quota, audited-site slots, monthly audit-run credits
- `/skills/report-an-issue.md` — Report a bug or relay feedback via `feedback.submit`

## Point your agent at Menciona

Show your agent how every AI model talks about your brand.

Get started: https://app.menciona.ai/signup