> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nephia.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> Your mentions, one prompt away — Nephia in Claude, Cursor, and any MCP client.

Ask your agent what people said about you, and let it read the answer out of Nephia.

```bash theme={null}
claude mcp add --transport http nephia https://api.nephia.cc/mcp
```

That is the whole install. Your browser opens once, you sign in and choose what the agent may do, and the connection is live — no API key to copy, nothing to paste.

The official MCP (Model Context Protocol) server exposes the product API (your mentions, your keywords, their buckets) as tools any model can call. It comes two ways: **remote**, at `https://api.nephia.cc/mcp` under OAuth, and **local**, as an [`npx`](https://www.npmjs.com/package/nephia-mcp) command under an [API key](/authentication).

## Try it

Once it is added, run the first recipe. In Claude Code, type `/` and pick `daily_brief`; other clients list prompts beside the tools.

The agent checks with `list_keywords` that every Source was checked on time, reads the last 24 hours with `list_mentions`, and answers with the five mentions to deal with first, each with the reason it is there:

```
Late: Reddit on "Nephia" was last checked 7 hours ago, hourly expected.

1. Reddit, r/SaaS, u/devtools_dan
   "Octolens or Nephia for a two-person team? We need X and Reddit."
   Why: matched "nephia", intent comparison, 14 comments
   https://reddit.com/r/SaaS/comments/...
   Next: a buyer comparing tools, worth reading today.

2. ...
```

Every call in that brief is free. `matchedTerms` on each mention says which of your terms caught it, and each Source's `health` on `list_keywords` and `get_keyword` says when it was last checked and whether it is `stale`, so a quiet morning and a Source nobody checked stop looking the same.

Or ask in plain language:

> What did Reddit say about us this week? Anything negative?

The agent calls `list_keywords` to find your keyword, then `list_mentions` with `source=reddit` and a week's `since`, and answers from the scored stream:

```
47 mentions on Reddit since Aug 24 — 38 positive, 6 neutral, 3 negative.

The negatives are all one theme: r/selfhosted (12 comments) on the webhook
retry window being too short for cold-start receivers.

Top thread: "Nephia vs Brand24 after 3 months" — 210 points, positive,
sorted into your "Comparisons" bucket.
```

Nothing was computed for that answer that the dashboard does not already show. What is new is that the agent could read it.

More prompts that map onto one or two calls:

* *"Any leads this week?"* → `list_mentions` with `intent=["purchase_intent", "comparison"]`
* *"Show me the pricing complaints on my Nephia monitor"* → `list_keyword_buckets`, then `get_keyword_results` with `bucket=`
* *"Find people who can't get it to deploy"* → `list_mentions` with `mode=semantic` (charged — see below)
* *"Pause my brand monitor while we're on holiday"* → `keyword_manage` with `action=pause`

## Clients

### Remote (recommended)

One URL, no key. The first call opens your browser: you sign in, a screen lists what the agent is asking for, and you decide. Works in any client that can add a remote MCP server — including the hosted ones that cannot run a local command.

**Claude Code**

```bash theme={null}
claude mcp add --transport http nephia https://api.nephia.cc/mcp
```

**Cursor**

`~/.cursor/mcp.json` for every project, or `.cursor/mcp.json` for one. A remote server is a `url` and nothing else — no `command`, no `args`, no `type`:

```json theme={null}
{
  "mcpServers": {
    "nephia": {
      "url": "https://api.nephia.cc/mcp"
    }
  }
}
```

Cursor registers itself and opens the browser on first use. Nothing to whitelist: its callbacks (`http://localhost:8787/callback` on desktop, `https://www.cursor.com/agents/mcp/oauth/callback` on web) are accepted as they are.

**Claude.ai, ChatGPT, and other hosted clients**

Add a custom connector and give it the server URL:

```
https://api.nephia.cc/mcp
```

**What the consent screen asks for**

| Permission | What it allows |
| - | - |
| Read your mentions and keywords | Every free read: mentions, keywords, buckets, monitors, credit balance |
| Change what is running | Create, edit, pause, resume or retire keywords and their Sources |
| Spend your credits | Semantic search, AI analyses, Vinted analytics |

The third one arrives **unticked**. An agent you leave it off for still reads everything — it just cannot spend, and it will say so when a call needs it, naming the permission you did not grant.

**Disconnecting**

Settings → API keys → Connected agents → Disconnect. The agent has to sign in again to reach your account. A token it is already holding keeps working until it expires, which is at most an hour.

### Local (stdio)

An API key and a local command. Right when you want no browser in the loop — a script, a CI job, a machine that is not yours to sign in on.

**Claude Code**

```bash theme={null}
claude mcp add nephia -e NEPHIA_API_KEY=YOUR_API_KEY -- npx -y nephia-mcp
```

**Claude Desktop, Cursor, and anything else reading an `mcpServers` config**

```json theme={null}
{
  "mcpServers": {
    "nephia": {
      "command": "npx",
      "args": ["-y", "nephia-mcp"],
      "env": { "NEPHIA_API_KEY": "YOUR_API_KEY" }
    }
  }
}
```

Needs Node ≥ 20. In Cursor this goes in the same `mcp.json` as the remote form above — a server entry is either a `url` or a `command`, never both.

<Note>
  Both paths serve the same tools from the same registry, and both bill the same way. Every call appears in [Spend](/credits) either way — under the key's name for a local server, under the agent's for a remote one.
</Note>

## Tools

Every tool description carries what it costs, so a model can budget before it spends. Check the balance any time with `account_credits`, which is free.

| Tool | What it does | Cost |
| - | - | - |
| `list_mentions` | List mentions | Free in text mode · 1 credit/semantic question |
| `mentions_stats` | Count mentions | Free |
| `mentions_similar` | Find similar mentions | 1 credit/mention asked about |
| `list_keywords` | List keywords | Free |
| `get_keyword` | Get a keyword | Free |
| `get_keyword_results` | List a keyword's mentions | Free in text mode · 1 credit/semantic question |
| `get_keyword_events` | Replay a keyword's raw events or activity | Free |
| `list_keyword_buckets` | List a keyword's buckets | Free |
| `keyword_manage` | Pause, resume, or retire a keyword | Free |
| `keyword_estimate` | Estimate a keyword or a change | Free |
| `keyword_create` | Create a keyword | Metered per check |
| `keyword_update` | Change keyword settings | Metered per check |
| `keyword_source_set` | Add or replace one of a keyword's sources | Metered per check |
| `keyword_source_manage` | Pause or resume one of a keyword's sources | Free |
| `keyword_bucket_manage` | Create or delete a bucket | Free |
| `keyword_brand_set` | See or set a keyword's brand | Free |
| `explore_estimate` | Estimate an Explore run | Free |
| `explore` | Explore the Sources once | 1 to 65 credits/search |
| `analyses_run` | Run an AI pass over items | 1/50 items (agent: 1/25) |
| `analyses_estimate` | Price an AI pass | Free |
| `vinted_price_history` | Get a Vinted item price history | 3 credits |
| `vinted_market_stats` | Get Vinted market price statistics | 5 credits |
| `account_credits` | Get credit balance | Free |

The Source is an **argument**, not a tool: `list_mentions` takes `source=reddit` rather than there being a `reddit_mentions` beside an `x_mentions`. One contract, one place to look.

## Prompts

Recipes your client lists beside the tools: in Claude Code, type `/` and pick one. A prompt is text the client inserts for you. It spends nothing and writes nothing, and every tool it names states its own cost; the ones that can charge are priced and put to you before they run.

| Prompt | Arguments | What it does |
| - | - | - |
| `daily_brief` | `hours` (optional), `keyword_id` (optional) | The five mentions to deal with first from the last day, each with why it is on the list, after checking that every Source was actually checked. Free: reads only. |
| `weekly_digest` | `days` (optional) | Volume by Source and sentiment, three themes and five verbatim quotes over the last week. Free unless the person agrees to an AI summary, which is priced first. |
| `set_up_monitoring` | `brand`, `site` (optional) | Propose what to track for a brand, show what it would cost a month, and create the keyword only after the person agrees to that figure. |
| `find_alternative_seekers` | `competitors`, `days` (optional) | A reading list of threads where someone looks for an alternative to a competitor or compares options, ranked by engagement. Free in the default text mode. |
| `collect_testimonials` | `days` (optional) | Verbatim positive quotes with author, Source, date and link, grouped by theme. Free unless the person agrees to an AI sort, which is priced first. |

## Skills

The same recipes as `SKILL.md` files, for an agent that runs them on a schedule: a daily brief, a weekly digest, mentions turned into issues, a wall of love, churn signals, alternative seekers. They ship in the `nephia-mcp` package and each one is on the [Skills](/skills) page in full.

* **`alternative-seekers`**: Build a reading list of threads where someone looks for an alternative to `{{competitors}}` or compares tools, ranked by engagement, from what Nephia caught.
* **`churn-signals`**: Spot customers of `{{brand}}` who may be leaving, from Nephia mentions that say cancel, switched or alternative, and from authors who complain again and again.
* **`daily-brief`**: Every morning, read what Nephia caught in the last 24 hours and deliver the five mentions of `{{brand}}` to deal with first, each with why it is on the list, after checking that every Source was actually checked.
* **`mentions-to-issues`**: Turn bug reports and feature requests about `{{brand}}` found by Nephia into issues in `{{issue_tracker}}` (Linear or GitHub), each linking back to the original mention, without duplicates.
* **`wall-of-love`**: Collect specific, positive quotes about `{{brand}}` from Nephia, each verbatim with author, Source, date and link, grouped by theme, ready for the person to request permission to reuse.
* **`weekly-digest`**: Once a week, summarise what people said about `{{brand}}` in Nephia, with volume by Source, the sentiment split, three themes and five verbatim quotes with links.

## Reading, and what it costs

Reading your own mentions is free, in any volume, because they are rows you already own. One thing charges: `mode="semantic"`.

| Mode | What it matches | Cost |
| - | - | - |
| `text` (default) | The substring, inside the window | Free |
| `semantic` | The **meaning** — `q="reliability complaints"` finds "this thing keeps crashing" | 1 credit per question, then cached 10 minutes |

The charge is per *question*, not per page or per result: paging through a semantic answer is free, and asking the same question twice inside ten minutes is one credit.

`mentions_similar` is the other paid read: the mentions closest in meaning to one the agent already has, charged per mention asked about and cached ten minutes for that mention only. Asking about a different mention charges again.

### Counting

"How many" is a question for `mentions_stats`, not for paging `list_mentions`. It counts the whole window in one free call, cut along one or two of `day`, `hour`, `source`, `sentiment`, `intent`, `author`, `term` and `keyword`, over up to 90 days. "Which Source carries the complaints" is `group_by ["source", "sentiment"]`; "which terms catch the most" is `group_by ["term"]`; comparing two weeks is one call per week. Authors, terms and keywords keep the busiest values and say when they cut. Dates are publication dates and the counts are the ones Insights shows, so they include mentions a mute rule or a hide keeps out of `list_mentions`. Page `list_mentions` afterwards to quote.

`list_mentions`, `get_keyword_results` and `mentions_similar` are annotated **non-read-only and non-idempotent** even though they are free by default, because an MCP annotation describes a tool rather than a call: a client's auto-approve list should have to say out loud that a tool which *can* debit the account is allowed to run unattended.

## Creating and changing monitors

An agent can create and change a keyword, priced first: `keyword_estimate` returns what the change costs a month and a token, and `keyword_create`, `keyword_update` and `keyword_source_set` refuse a body that estimate did not price. `keyword_source_set` prices itself: a first call with `mode: "estimate"` returns the figure and the token, a second with `mode: "write"` and that token saves, and only `applied: true` is a save. A tool that writes refuses an argument it does not declare and names it, so a misspelt key is an error and never a silent no-op. The `set_up_monitoring` prompt walks through it and waits for you to agree to the figure. Rules, buckets, channels and schedules are still easiest to read in the [dashboard](https://nephia.cc/dashboard), and an agent can pause, resume or retire any keyword, which is also how you stop it spending.

### Asking once

Before a monitor exists, an agent can ask the Sources once with `explore`, without creating a keyword. It is the way to test an angle first: a competitor's name, "alternative to", "anyone know a tool". The round trip is the same as a keyword write: `explore_estimate` prices the exact arguments per search and returns a token, and `explore` refuses arguments it did not price. A run charges each search once, at its Source's rate. Its outcomes say, per search, whether the platform answered and what the criteria kept, and the run is kept: `list_mentions` with `run` reads it again for free. The `find_alternative_seekers` prompt reaches for it when the stream holds little. See [Explore](/explore).

<h3 id="keyword-events">
  Reading without a webhook
</h3>

A keyword's `webhookUrl` must be a **publicly reachable URL you control**; an agent asks for it and never invents one. Without a receiver, `get_keyword_events` reads the same thing for free: `kind=events` replays the raw events in the exact body the webhook delivers (including the types a mention does not carry, such as Vinted's `listing.price_changed`), `kind=activity` answers "is it polling, and did my webhook answer?", and `kind=runs` lists the stored AI answer runs. For reading what people said, `get_keyword_results` is the better tool: a mention is the same catch, projected to a title and a body. See [Keywords](/keywords#events) and [Webhooks](/webhooks#replay).

## Errors

Tool results carry actionable error text instead of raw failures: `401` tells you to reconnect on the remote server and points to `NEPHIA_API_KEY` on the local one, `402` to [credits](/credits) (check with `account_credits`), `404` means not found *or* not yours (never a `403`, which would confirm someone else's keyword exists), and `429/503` include the retry delay. The underlying client already retries 429/502/503/504 with backoff, never timeouts or other 4xx.

On the remote server one more refusal exists: a call the connection was not granted. It comes back as a tool result naming the missing permission, not as a broken connection — reconnect and allow it on the consent screen.

## Large responses

Mention lists are shaped for a context window before they reach the model: capped at 25 items per call by default, bodies truncated, screen-only fields (thumbnails, captions, the label/value grid) dropped, and sentiment, intent, bucket, author and URL kept. To count, call `mentions_stats` rather than raising `limit`.

Beyond that, any response over 50 000 characters is truncated with an explicit notice — narrow the request or page with the returned cursor. Override with the `NEPHIA_MCP_MAX_OUTPUT_CHARS` env var.

## Next steps

* [Skills](/skills): the recipes as files, for a scheduled agent
* [Command line](/sdk#command-line): the same API from a shell, for a cron job that needs no session
* [Quickstart](/quickstart)
* [SDK (Node.js)](/sdk)
* [Credits](/credits)
* [API Reference](/api-reference/overview)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.