---
title: "MCP server"
description: "Connect Claude Code, Cursor, Codex, Gemini, VS Code and any MCP client to your mention feed."
canonical: https://docs.mentio.dev/mcp
markdown: https://docs.mentio.dev/mcp.mdx
---
# MCP server
Connect Claude Code, Cursor, Codex, Gemini, VS Code and any MCP client to your mention feed.
Mentio runs a hosted [Model Context Protocol](https://modelcontextprotocol.io) server. Point an MCP client at it and your agent can search and triage mentions, manage keywords and the company profile, read analytics, and configure alerts, people and segments, in your workspace, with the same rules as the dashboard.
```
https://mcp.mentio.dev/mcp
```
* **Hosted, streamable HTTP.** Nothing to install or run locally. Every tool call is authenticated and every request is stateless, so it works from editors, terminals, sandboxed agents and browser-based tools alike.
* **Sign in, or use a key.** Clients that implement MCP authorization (Claude Code, Cursor, Codex, claude.ai, ChatGPT) discover the OAuth server, open the browser, and get their own token after you approve: nothing to paste. Anything else sends an API key as a Bearer header. Either way a `read` scope exposes the read tools only; `write` exposes all of them.
* **40 tools**, one per operation of the [REST API](/conventions), validated with the same schemas and answering with the same shapes. Full list in [Tools](/mcp/tools).
## Quick start
### Add the server
With OAuth, the URL is all the client needs: `claude mcp add --transport http mentio https://mcp.mentio.dev/mcp`, or the same URL in Cursor, Codex, claude.ai or ChatGPT. The client asks Mentio where to sign in, opens the browser, and you approve on a consent page that names the client and the workspace. Every client's exact steps are in [Installation instructions](#installation-instructions) below.
Prefer a key (CI, a server, a client without OAuth)? Open [API Keys](https://app.mentio.dev/api-keys) and create one: `read` to let an agent explore safely, `write` to let it act. The key is shown once. Paste it above and the snippets below fill it in.
### Ask
Restart or reload the client if it does not pick the server up at once, then try: "What are the negative mentions of our brand this week, and what are they about?"
## Authentication
Every tool call carries a Bearer credential in the `Authorization` header. Two kinds work, and the server treats them alike:
```
Authorization: Bearer
Authorization: Bearer mk_live_...
```
**OAuth 2.1** (the [MCP authorization spec](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization)). A call without a credential answers `401` with `WWW-Authenticate: Bearer resource_metadata=...`; the metadata names the authorization server (`https://app.mentio.dev`), which publishes RFC 8414 metadata, open dynamic client registration and PKCE. The client registers itself, opens the browser at the authorize endpoint, you sign in and approve on a consent page that names the client, and the client exchanges the code for an access token (one hour) and, with `offline_access`, a refresh token (thirty days) it rotates by itself. No key is ever shown or pasted.
* **Workspace.** A token identifies you, not a workspace. The consent page asks which workspace the client may act on when you belong to several; otherwise it is your workspace. Signed-in users on one workspace never see the question.
* **Scopes.** `read` and `write`, the same two the keys have. A grant that did not ask for `write` acts as `read`.
* **Consent every time.** Every authorization goes through the consent page, so a signed-in browser never grants a client silently.
**API keys.** Created in the dashboard under [API Keys](https://app.mentio.dev/api-keys) or with [`POST /v1/api-keys`](/authentication), stored hashed and shown once. A key belongs to one workspace. A `read` key lists and runs only the read tools; a `write` key all of them; calling a write tool with a read key fails with `read_only_key`. Revoking a key in the dashboard disconnects the client within a minute (keys are cached briefly for speed).
* **Discovery needs no key.** `initialize`, `tools/list` and the resources answer without one, so a client or a registry can read what the server offers before a person adds a key. A key that is sent is always verified, and `tools/call` always needs one.
Custom connectors on claude.ai, Claude Desktop, Claude Managed Agents and ChatGPT authenticate with OAuth: add `https://mcp.mentio.dev/mcp` as a custom connector, sign in when asked, done. The mcp-remote bridge is no longer needed.
## Resources
Besides the tools, the server exposes four read-only resources (`resources/list`, `resources/read`), public documents an agent can read through MCP without leaving the protocol. Each is addressed by its own URL and returned with its mime type.
| Resource | URI | What it is |
| --------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `openapi` | `https://api.mentio.dev/v1/openapi.json` | The REST API the tools mirror, with every schema. |
| `docs` | `https://docs.mentio.dev/llms.txt` | When to use Mentio, how to call it, and every documentation page in Markdown. |
| `skill` | `https://mentio.dev/.well-known/agent-skills/mentio/SKILL.md` | How an agent should use the API, area by area. |
| `auth` | `https://mentio.dev/auth.md` | How to get and send an API key. |
Every tool carries MCP annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`), so a client knows which calls to confirm with you before running them: the read tools are read-only and idempotent, the updates are idempotent, and `delete_segment` and `merge_people` are the two marked destructive.
The server card at [`/.well-known/mcp.json`](https://mcp.mentio.dev/.well-known/mcp.json) (also at `/.well-known/mcp/server-card.json`) describes the transport, the authentication, the capabilities and previews the tools for registries.
## Documentation MCP server
The documentation has its own MCP server, read-only and keyless, so an agent can answer questions from the docs over the same protocol it uses to act:
```
https://docs.mentio.dev/api/mcp
```
* **Tools:** `search_docs` (full-text search, the same index as the search box), `read_page` (any page as Markdown, by path such as `/quickstart` or `/api/mentions/search-mentions`) and `list_pages` (every page with its title and description).
* **Resources:** `https://docs.mentio.dev/llms.txt` and every page at its `.mdx` address.
* **Card:** [`/.well-known/mcp.json`](https://docs.mentio.dev/.well-known/mcp.json).
## Security
* **Least privilege by key.** Explore with a `read` key; hand out a `write` key only to an agent that should change things. Write tools can update mentions, add and mute keywords, edit the company profile, create and change alerts, annotate and merge people, and save or delete segments. No MCP tool deletes keywords, mentions or channels, and nothing touches billing.
* **Every call is attributed.** Tool calls run as the workspace the key belongs to and are subject to the same limits and validation as the REST API; the dashboard's Activity views reflect what an agent changed.
* **Stateless server.** There is no session to hijack: each request carries its own key, and the server keeps nothing between calls.
* **Keep the key out of repositories.** Prefer user-level config (`~/.cursor/mcp.json`, `claude mcp add` without `--scope project`) or an environment variable where the client supports it (Codex's `bearer_token_env_var`, the `env` block of the Claude Desktop bridge). If a key leaks, revoke it in the dashboard and create a new one.
## Installation instructions
Each client below needs two things: the server URL `https://mcp.mentio.dev/mcp` and the `Authorization: Bearer mk_live_...` header. The interactive block at the top fills your real key into every snippet.
One click: use **Install in Cursor** at the top of this page (it carries the header). Manually:
1. Open the command palette and type "Cursor Settings".
2. Under "Tools & MCP" click "New MCP Server".
3. Paste the following into the file that opens (project `.cursor/mcp.json`, or `~/.cursor/mcp.json` for every project):
```json title=".cursor/mcp.json"
{
"mcpServers": {
"mentio": {
"url": "https://mcp.mentio.dev/mcp",
"headers": {
"Authorization": "Bearer mk_live_..."
}
}
}
}
```
4. Save. Cursor connects at once; if it shows the server as disconnected, restart Cursor.
One click: **Install in VS Code** at the top of this page. Manually:
1. Command Palette (`Cmd+Shift+P` on macOS, `Ctrl+Shift+P` elsewhere), "MCP: Add Server", choose **HTTP**.
2. URL `https://mcp.mentio.dev/mcp`, name `mentio`.
3. Open the generated `.vscode/mcp.json` and add the header:
```json title=".vscode/mcp.json"
{
"servers": {
"mentio": {
"type": "http",
"url": "https://mcp.mentio.dev/mcp",
"headers": {
"Authorization": "Bearer mk_live_..."
}
}
}
}
```
4. "MCP: List Servers", select mentio, "Start Server". Copilot Chat in agent mode then lists the Mentio tools.
```bash
claude mcp add --transport http mentio https://mcp.mentio.dev/mcp
```
Then, inside Claude Code, `/mcp`, pick mentio and choose Authenticate: the browser opens on Mentio, you sign in and approve, and the server shows as connected. Add `--scope project` to write the server into the repository's `.mcp.json` (safe now: it holds only the URL) or `--scope user` for every project.
With a key instead, add the header and skip the browser:
```bash
claude mcp add --transport http mentio https://mcp.mentio.dev/mcp \
--header "Authorization: Bearer mk_live_..."
```
With OAuth:
```bash
codex mcp add mentio --url https://mcp.mentio.dev/mcp
codex mcp login mentio
```
The second command opens the browser; approve and `/mcp` inside Codex lists mentio as enabled. With a key, Codex reads it from an environment variable, so the config file never holds it:
```bash
export MENTIO_API_KEY="mk_live_..."
codex mcp add mentio --url https://mcp.mentio.dev/mcp --bearer-token-env-var MENTIO_API_KEY
```
Or edit the config directly:
```toml title="~/.codex/config.toml"
[mcp_servers.mentio]
url = "https://mcp.mentio.dev/mcp"
bearer_token_env_var = "MENTIO_API_KEY"
```
Inside Codex, `/mcp` lists mentio as enabled.
```json title="~/.gemini/settings.json"
{
"mcpServers": {
"mentio": {
"httpUrl": "https://mcp.mentio.dev/mcp",
"headers": {
"Authorization": "Bearer mk_live_..."
}
}
}
}
```
Inside Gemini, `/mcp list` shows the server connected. `httpUrl` selects the streamable HTTP transport.
```json title="~/.config/opencode/opencode.json"
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"mentio": {
"type": "remote",
"url": "https://mcp.mentio.dev/mcp",
"headers": {
"Authorization": "Bearer mk_live_..."
}
}
}
}
```
The file can live in a project or globally; `/mcp` inside OpenCode lists mentio as connected.
```json title="~/.codeium/windsurf/mcp_config.json"
{
"mcpServers": {
"mentio": {
"serverUrl": "https://mcp.mentio.dev/mcp",
"headers": {
"Authorization": "Bearer mk_live_..."
}
}
}
}
```
```json title="~/.config/amp/settings.json"
{
"amp.mcpServers": {
"mentio": {
"url": "https://mcp.mentio.dev/mcp",
"headers": {
"Authorization": "Bearer mk_live_..."
}
}
}
}
```
On grok.com: Settings, Connectors, New connector, Custom, URL `https://mcp.mentio.dev/mcp`, and leave authentication empty. Grok discovers the OAuth server, opens the Mentio sign-in, and keeps the token after you approve. Ask it to list your Mentio keywords to confirm.
```yaml title="~/.hermes/config.yaml"
mcp_servers:
mentio:
url: "https://mcp.mentio.dev/mcp"
auth: oauth
```
Then `hermes mcp login mentio` opens the browser; approve, and Hermes stores the token under `~/.hermes/mcp-tokens/`. With a key instead, replace `auth: oauth` with `headers: { Authorization: "Bearer ${MENTIO_API_KEY}" }` and put the key in `~/.hermes/.env`.
Claude Desktop connects to remote servers over OAuth, which is now the direct route: Settings, Connectors, Add custom connector, URL `https://mcp.mentio.dev/mcp`, then Connect and sign in. The `mcp-remote` bridge below remains for a key-based setup (a shared machine, a key with a narrower scope). Needs Node.js.
```json title="claude_desktop_config.json"
{
"mcpServers": {
"mentio": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://mcp.mentio.dev/mcp", "--header", "Authorization:${MENTIO_AUTH}"],
"env": {
"MENTIO_AUTH": "Bearer mk_live_..."
}
}
}
}
```
The file is under Settings, Developer, Edit Config. Restart Claude Desktop afterwards. The `${MENTIO_AUTH}` indirection is the documented way to pass a header with a space through mcp-remote.
Use the streamable HTTP transport with the URL and the header. Most clients accept this shape:
```json
{
"mcpServers": {
"mentio": {
"type": "http",
"url": "https://mcp.mentio.dev/mcp",
"headers": {
"Authorization": "Bearer mk_live_..."
}
}
}
}
```
Clients that implement MCP authorization need only the URL; the header is for the rest.
OpenClaw does not need the MCP server: install the `mentio` skill from ClawHub and it calls the API directly. See [OpenClaw](/integrations/openclaw).
## Help your agent target your workspace
An agent that knows what you track wastes fewer calls. Put the essentials in your `AGENTS.md` (or `CLAUDE.md`, or the client's rules file):
```markdown title="AGENTS.md"
## Mentio
- Workspace: Acme (the `mentio` MCP server is connected to it)
- Brand keyword: `acme`; competitors: `globex`, `initech`; topic: `api rate limiting`
- "Relevant" means the classifier scored it relevant; matched counts include noise
- Use `search_mentions` with a time range first; `get_analytics_*` for numbers over a window
- Do not change alerts or keywords unless asked; triage (status, assignee, notes) is fine
```
## What you can ask
Once connected, ask your agent things like:
* "Any negative mentions of our brand this week? Summarize the themes and link the three worst."
* "Search mentions of `acme` on Hacker News with buying intent and draft a reply for each."
* "Mark every mention I already replied to as done and assign the open ones about pricing to Dana."
* "Start tracking `acme-cli` as a brand keyword, only on GitHub and Hacker News."
* "Our classifier keeps flagging irrelevant posts. Update the company context: we sell developer tooling, not roofing."
* "How did mention volume split across platforms over the last 30 days, compared with the 30 before?"
* "Who are the ten people who mention us most, and which have over 5k followers? Tag them `advocate`."
* "Create a daily digest at 9am Madrid time to our Slack channel with only negative mentions."
* "Share of voice against `globex` this quarter."
## How the tools behave
* **Same contract as the REST API.** Inputs are validated with the same schemas and errors carry the same codes, so an agent that has read the [API reference](/api) already knows the shapes. Responses are the same JSON.
* **Lists are bounded.** `search_mentions` returns 10 mentions by default (up to 100) and has no cursor: an agent narrows the filters instead of paging. `sort: "priority"` ranks the last 30 days of matches; `newest` has no window.
* **Writes need a write key.** With a read key the write tools are not even listed.
* **Protocol.** Streamable HTTP, stateless: `POST /mcp` with JSON-RPC, one JSON response per request, no `Mcp-Session-Id`, no server-initiated stream. Protocol versions `2025-06-18`, `2025-03-26` and `2024-11-05` are accepted; notifications are acknowledged with 202. Opening the URL in a browser brings you to this page.
## Available tools
Grouped by area; the [Tools](/mcp/tools) page has every input.
* **Mentions**: `search_mentions`, `get_mention`, `update_mention` (status, assignee, snooze, note), `get_mention_stats`.
* **Keywords**: `list_keywords`, `add_keyword`, `update_keyword` (platforms, mute).
* **Company**: `get_company`, `update_company` (the context the classifier reads).
* **Analytics**: `get_analytics_summary`, `get_analytics_series`, `get_analytics_breakdown`, `get_share_of_voice`, all over one window grammar (`range` or `from`/`to`, keywords, platforms, timezone, compare).
* **Alerts**: `list_alerts`, `create_alert`, `update_alert`, `list_channels`.
* **People**: `list_people`, `get_person`, `update_person` (tags, notes, mute), `merge_people`, `split_person`.
* **Segments**: `list_segments`, `create_segment`, `update_segment`, `delete_segment`.
Read tools carry the `readOnly` annotation, so clients that ask before running side-effecting tools do the right thing without configuration.
## Troubleshooting
If your client cannot connect or tools fail to run:
1. **401 "Missing or invalid API key"**: the header did not arrive or the key is wrong. Check the exact shape `Authorization: Bearer mk_live_...` (one space, no quotes inside the value) and that the key has not been revoked. With Codex, confirm the environment variable is exported in the shell that starts Codex.
2. **The server is listed but no tools appear**: reload or restart the client; some fetch the tool list only when a session starts. With a `read` key, only the read tools are listed by design.
3. **"Needs authentication" or an OAuth prompt**: that is the normal path; approve it in the browser. If the client cannot open a browser (CI, a server), send an API key as the header instead.
4. **A write tool answers `read_only_key`**: the key is `read`. Create a `write` key for that client.
5. **405 or 404 from the URL**: only `POST /mcp` speaks MCP; a browser visit redirects here. If your client insists on `GET` for a server-initiated stream, it is using the older SSE transport; choose streamable HTTP.
6. **Rate or size errors**: list tools are capped at 100 rows, exports are not available over MCP, and the API's per-workspace limits apply. Narrow the filters and try again.
## Need help?
Open the chat bubble in the [dashboard](https://app.mentio.dev) and we answer there, or write to the support channel from the same window. Include the client you use and the tool call that failed.