> ## 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 queries, 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, ask in plain language: > What did Reddit say about us this week? Anything negative? The agent calls `list_queries` to find your monitor, 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_query_buckets`, then `get_query_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"* → `query_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 Queries | Every free read: mentions, Queries, buckets, monitors, credit balance | | Change what is running | Pause, resume or retire a Query; create, edit and remove Watches | | 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. 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. ## 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 | | `list_queries` | List queries | Free | | `get_query` | Get a query | Free | | `get_query_results` | List a query's mentions | Free in text mode · 1 credit/semantic question | | `list_query_buckets` | List a query's buckets | Free | | `query_manage` | Pause, resume, or retire a query | Free | | `query_estimate` | Estimate a query or a change | Free | | `query_create` | Create a query | Metered per check | | `query_update` | Change query settings | Metered per check | | `query_source_set` | Add or replace one of a query's sources | Metered per check | | `query_source_manage` | Pause or resume one of a query's sources | Free | | `query_bucket_manage` | Create or delete a bucket | Free | | `query_brand_set` | See or set a query's brand | Free | | `watch_create` | Create a watch | Metered per tick | | `watch_list` | List watches | Free | | `watch_manage` | Pause, resume, or delete a watch | Free | | `watch_feed` | Get watch events or activity | Free | | `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. ## 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. `list_mentions` and `get_query_results` 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 Queries are configured in the [dashboard](https://nephia.cc/dashboard), not from an agent: a Query carries rules, buckets, delivery channels, an activation schedule and per-source search overrides, and a monitor composed blind is a meter nobody reads. The MCP server can *read* every Query, and can pause, resume or retire one — which is also how you stop it spending. Watches — the single-source, webhook-first primitive underneath — can be created from an agent with `watch_create`. It needs a **publicly reachable `webhookUrl` you control**; ask for it, never invent one. Without a receiver, poll matches with `watch_feed` (`kind=events`) and delivery outcomes with `kind=activity`, both free. See [Watches](/watches) and [Webhooks](/webhooks). ## 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 Query 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. Ask for a bigger `limit` to count, not to read. 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 * [Quickstart](/quickstart) * [SDK (Node.js)](/sdk) * [Credits](/credits) * [API Reference](/api-reference/overview)