MCP server

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

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 command under an API key.

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

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:

{
  "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

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

{
  "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 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
`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 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, 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.

Reading without a webhook

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 and 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 (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: the recipes as files, for a scheduled agent
Command line: the same API from a shell, for a cron job that needs no session
Quickstart
SDK (Node.js)
Credits
API Reference

Guides

Sources

Integrations

API Reference

Try it

Clients

Remote (recommended)

Local (stdio)

Tools

Prompts

Skills

Reading, and what it costs

Counting

Creating and changing monitors

Asking once

Reading without a webhook

Errors

Large responses

Next steps

​Try it

​Clients

​Remote (recommended)

​Local (stdio)

​Tools

​Prompts

​Skills

​Reading, and what it costs

​Counting

​Creating and changing monitors

​Asking once

​Reading without a webhook

​Errors

​Large responses

​Next steps

Try it

Clients

Remote (recommended)

Local (stdio)

Tools

Prompts

Skills

Reading, and what it costs

Counting

Creating and changing monitors

Asking once

Reading without a webhook

Errors

Large responses

Next steps