The Mentionable MCP uses bearer-token authentication with workspace-scoped API keys. There are two ways to get a token: paste a static API key (best for Claude Desktop, Cursor, n8n, scripts), or connect via OAuth (for hosted connectors like ChatGPT and Claude that only expose a Connect button). Both resolve to the same mnt_sk_ key under the hood, so everything below (scopes, roles, rate limits) applies to both.

Video walkthrough

Watch how to create a Mentionable API key and connect it to Claude or ChatGPT.

How does Mentionable MCP authentication work?

Every request sends a bearer token in the Authorization header. The token starts with mnt_sk_, is hashed server-side with SHA-256, and resolves to a workspace member with project-scoped permissions. The token is verified, the rate limit is checked, the tool is dispatched.

API keys

Mentionable API keys are created and managed in Settings → API Keys (MCP) at mentionable.ai.

Property	Value
Prefix	`mnt_sk_`
Random part	32 base64url characters
Storage	SHA-256 hash only — plaintext is shown once
Ownership	Bound to one workspace member
Scope	Inherits member permissions, optionally narrowed to specific projects
`lastUsedAt`	Updated on every successful call

Sending the token

Two transports are accepted, in this order:

Authorization header — preferred:
```
Authorization: Bearer mnt_sk_xxx
```
Query parameter — for clients that cannot set headers (some webhook tools):
```
POST https://mentionable.ai/api/mcp?key=mnt_sk_xxx
```
The parameter name apiKey is also accepted. Avoid this when possible — query strings end up in server logs.

Connecting with OAuth (ChatGPT and Claude connectors)

Hosted connectors, like ChatGPT connectors and Claude custom connectors, do not accept a pasted API key. They expect an OAuth 2.1 flow behind a Connect button. Mentionable supports this out of the box, so you never copy a token by hand.

How to connect

In the connector setup, add a custom MCP server with the URL https://mentionable.ai/api/mcp.
Click Connect. The connector discovers the authorization server and opens a Mentionable consent screen.
Log into mentionable.ai if you are not already, then click Approve.
Done. The connector is authenticated. There is no token to copy or store.

Managing OAuth connections

Each connector you approve appears in Settings → API Keys (MCP) named MCP OAuth (host), for example MCP OAuth (claude.ai). To disconnect a connector, revoke that key. OAuth access tokens do not expire on their own, so revocation is how you cut off access.

OAuth, like static keys, requires the Pro or Agency plan. A Growth (or lower) workspace gets access_denied when the connector tries to obtain a token.

Which mode should I use?

Client	Recommended auth
ChatGPT connectors, Claude web custom connectors	OAuth (the Connect button)
Claude Desktop, Cursor, VS Code	Static API key pasted as a bearer token
n8n, cron jobs, custom scripts	Static API key (header or query param)

Static keys are simpler for anything that reads a config file or an environment variable. OAuth is for the hosted "Connect" experience where pasting a token is not an option.

Project scopes

Effective project scope is the intersection of two layers:

Layer	Empty list means	Non-empty list means
Workspace member scope	Access to all projects in the tenant	Whitelist of project IDs
API key scope	Inherits member scope	Further narrows to specific project IDs

A tool call against a project outside the effective scope returns:

{ "error": { "code": "FORBIDDEN", "message": "Project not in API key scope" } }

Write tools (bulk_update_competitor_status) additionally require the member's role to be at least member. The customer role is read-only and cannot mutate competitor status.

Rate limits

The Mentionable MCP applies a 100-request-per-60-second rate limit per API key, using a sliding window in Redis.

When the limit is hit:

HTTP/1.1 429 Too Many Requests
Retry-After: 17
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1714128037

Pagination counts as one request per page. A loop walking 200 prompts at limit: 20 is 10 requests. Plan for backoff if you orchestrate many tool calls from a single key.

Revoking a key

Open Settings → API Keys (MCP), find the key by its prefix and creation date, click Revoke. Any client using the key gets 401 on the next call. This is immediate and cannot be undone.

When rotating keys:

Issue a new key.
Update the client configuration (Claude Desktop, Cursor, n8n).
Verify the new key works with a tools/list call.
Revoke the old key.

Best practices

One key per client. Do not share claude-desktop between team members.
Name keys after their consumer: n8n-monthly-report, cursor-alex, gha-cron-veille.
Restrict keys to a single project when the consumer only needs one.
Rotate quarterly. Revoke the old key after the new one is wired up.
Never commit keys to git. Use environment variables or your client's secret store.

What an API key does not do

It cannot create or delete projects.
It cannot modify billing or subscription state.
It cannot read another workspace's data.
It cannot bypass the workspace member's project scope.

The Mentionable MCP is read-mostly. Today, three write tools are exposed: bulk_update_competitor_status (triage suggested competitors), bulk_update_reddit_thread_status (triage Reddit threads) and enrich_reddit_thread (trigger a Bright Data scrape, charges credits). New write tools are announced through the regular product release notes.