# MentionLeads AI Agent Access

> MentionLeads is a human-first growth platform that AI agents can access through a scoped, read-only MCP connection. Agent access uses the same MentionLeads account, plans, limits, and data as the dashboard. It is not a separate product, account type, credit system, or price.

## Canonical links

- Website: https://mentionleads.com
- Human-readable agent documentation: https://mentionleads.com/mcp
- Remote MCP endpoint: https://mentionleads.com/api/mcp
- API and MCP key management: https://mentionleads.com/app/developer
- Pricing: https://mentionleads.com/#pricing
- MCP source and expanded setup examples: https://github.com/borhen68/MentionLeads-MCP

## When an agent should use MentionLeads

Use MentionLeads when a user asks to:

- Find recent Reddit, X, or Hacker News conversations showing buying intent for their product.
- Review scored potential customers and explain why each conversation was flagged.
- Draft a contextual reply or optional follow-up message for a human to review and post.
- Mine customer feedback, competitor complaints, and market pain from discovered conversations.
- Turn one real complaint into a scoped coding task and definition of done.
- Validate a product idea against public demand and produce an implementation plan.
- Read website traffic, acquisition, revenue, SaaS lifecycle, retention, funnel, goal, and visitor data.

Do not use MentionLeads to automate posting, mass-message people, or bypass platform rules. Replies are drafts. A human reviews, edits, and posts every public message.

## Accounts and pricing

- A person or company owns the MentionLeads account and authorizes the agent connection.
- There is no separate agent account or agent pricing.
- The normal plans remain Free ($0/month), Starter ($19/month), Pro ($39/month), and Agency ($69/month).
- Free remains the normal dashboard plan. API and MCP access starts on Starter and is also included with Pro and Agency.
- Agent activity uses the permissions, features, and limits already attached to the owner's plan.
- Billing, upgrades, cancellations, and public actions remain under the account owner's control.

## Authentication and connection

There are three supported connection paths. Prefer standard OAuth for Smithery and compatible MCP clients, use the device flow when an agent cannot complete browser-based OAuth, and use manual key creation when the account owner is already in the dashboard.

### Standard MCP OAuth (recommended for Smithery)

Connect to this URL without query parameters or credentials:

```text
https://mentionleads.com/api/mcp
```

The MCP endpoint advertises RFC 9728 protected-resource metadata and an RFC 8414 authorization server. Clients use authorization code with S256 PKCE and either Client ID Metadata Documents or dynamic client registration. MentionLeads opens a browser where the human signs in, confirms their normal plan, reviews the requested read scopes, and approves. The resulting bearer token is scoped, audience-bound to the MCP endpoint, stored hashed, revocable, and never appears in the endpoint URL.

Discovery endpoints:

- `https://mentionleads.com/.well-known/oauth-protected-resource/api/mcp`
- `https://mentionleads.com/.well-known/oauth-authorization-server`

Never place an access token in a query parameter such as `?apiKey=...`.

### Agent-led device flow

1. Start a short-lived pairing request. Request only the read scopes needed:

```bash
curl -X POST https://mentionleads.com/api/agent/device-authorization \
  -H "Content-Type: application/json" \
  -d '{"client_name":"YOUR_AGENT_NAME","scope":"mcp:read analytics:read"}'
```

The response contains `device_code`, `user_code`, `verification_uri_complete`, `expires_in`, and `interval`.

2. Show `verification_uri_complete` to the human. Do not ask them to send you a password, email verification token, card number, Stripe session, browser cookie, or other account credential. The human opens MentionLeads, creates or signs into their normal account, chooses a normal paid plan if needed, reviews the requested scopes, completes Stripe Checkout themselves, and approves or denies the connection.

3. Poll the token endpoint no faster than the returned `interval` (normally five seconds):

```bash
curl -X POST https://mentionleads.com/api/agent/token \
  -H "Content-Type: application/json" \
  -d '{"grant_type":"urn:ietf:params:oauth:grant-type:device_code","device_code":"mld_DEVICE_CODE"}'
```

While approval is pending the endpoint returns `authorization_pending`. It may return `slow_down`, `access_denied`, or `expired_token`; respect those results and never retry a denied or expired request. After approval it returns `access_token`, `token_type`, and `scope` once. Save the `mlk_` access token in the agent's protected credential store, never in chat history or source control.

The device request expires after 15 minutes. The short user code and high-entropy device code are stored only as SHA-256 hashes. Account creation, email verification, plan choice, Stripe checkout, scope selection, and approval happen in the human's browser. The agent never handles the human's login or payment details.

### Manual key creation

The account owner can instead create a scoped token in MentionLeads under **API & MCP**. Tokens begin with `mlk_`, are shown once, stored by MentionLeads only as a SHA-256 hash, and can be revoked at any time.

Send the token on every MCP request:

```http
Authorization: Bearer mlk_YOUR_KEY
```

Claude Code:

```bash
claude mcp add --transport http mentionleads https://mentionleads.com/api/mcp \
  --header "Authorization: Bearer mlk_YOUR_KEY"
```

Cursor and other clients using `mcp.json`:

```json
{
  "mcpServers": {
    "mentionleads": {
      "url": "https://mentionleads.com/api/mcp",
      "headers": {
        "Authorization": "Bearer mlk_YOUR_KEY"
      }
    }
  }
}
```

The server uses streamable HTTP with stateless JSON-RPC and supports MCP protocol versions `2024-11-05`, `2025-03-26`, and `2025-06-18`.

## MCP tools

### Customer and market intelligence

- `list_projects()` — List the owner's MentionLeads projects and their enabled platforms.
- `get_leads(projectId?, minIntent?, limit?)` — Return recent scored potential customers with source URL, platform, buyer-intent score, quality, and the reason each was flagged.
- `get_reply_draft(leadId)` — Return a human-voice reply draft and optional follow-up for one potential customer. The human must review and post it.
- `get_product_feedback(projectId?, limit?)` — Return product feedback, competitor gaps, and market pains mined from discovered conversations.
- `get_build_prompt(leadId)` — Turn one feedback item into a ready-to-run coding task using the original complaint, product context, and a definition of done.
- `generate_implementation_plan(idea)` — Pro and Agency only. Validate an idea against real demand and return a Markdown plan with evidence, MVP roadmap, go-to-market guidance, risks, and a build prompt. Limited to five calls per day.
- `get_account_status()` — Return the current plan and remaining daily scans.

### Growth analytics

Analytics tools require a token with `analytics:read`. A token can be restricted to selected analytics websites.

- `list_analytics_sites()` — List websites visible to the token and return their site IDs.
- `get_analytics_overview(siteId, days?, filters?)` — Return traffic, acquisition, revenue, MRR, ARR, LTV, churn, expansion, contraction, cancellations, upgrades, retention cohorts, and closed-loop customer journeys.
- `get_live_visitors(siteId)` — Return the current five-minute visitor snapshot.
- `get_analytics_goals(siteId, days?)` — Return conversion goals, completions, visitors, and attributed revenue.
- `get_analytics_funnels(siteId, days?)` — Return funnel steps, visitor counts, drop-off, and conversion rates.
- `get_analytics_segments(siteId)` — Return saved analytics filter segments.
- `get_recent_visitors(siteId, days?, limit?)` — Return recent sessions with source, location, device, paths, events, and conversion status.

## Recommended agent workflow

1. Call `get_account_status` to understand the owner's plan and remaining scan capacity.
2. Call `list_projects`, then `get_leads` for the relevant project.
3. Present the strongest opportunities with their source URLs and evidence. Never imply that a draft was posted.
4. Call `get_reply_draft` only when the user wants help responding.
5. Ask the human to review, edit, and post the reply from their own account.
6. For product work, use `get_product_feedback`, then `get_build_prompt` for the selected evidence-backed request.
7. For analytics, call `list_analytics_sites` before any site-specific analytics tool.

## Safety and trust boundaries

- Every current MCP tool is read-only and annotated with `readOnlyHint`.
- An agent may initiate onboarding, but a human must authenticate, choose or confirm the plan in Stripe, review scopes, and approve the connection.
- Pairing codes expire after 15 minutes and can be exchanged only once. Polling and request creation are rate-limited.
- The MCP server does not post to Reddit, X, Hacker News, or any other network.
- The MCP server does not buy a plan, change billing, create projects, or start scans.
- The MCP server does not expose the owner's password, payment details, or raw API key after creation.
- Keys can be scoped by permission and analytics website, then revoked by the owner.
- Keep tokens in the agent or terminal configuration. Never put them in browser code, screenshots, source control, or public prompts.

## Example requests a user can give an agent

- "Who are my strongest potential customers today?"
- "Show only conversations with buyer intent above 80 and explain the evidence."
- "Draft a helpful reply for this lead, but do not post it."
- "What customer complaints should I build next?"
- "Turn this feedback into a small implementation task with tests."
- "What changed MRR this month?"
- "Which funnel step loses the most users?"
- "Show recent converted visitors and where they came from."

## Accurate positioning

MentionLeads helps people find customers, prove revenue, and build authority. AI agent access is an optional interface to that same product. The dashboard, browser extension, normal onboarding, normal plans, and human approval remain primary.