Authentication

The Mentionable MCP uses bearer-token authentication with workspace-scoped API keys.

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:

1. Authorization header — preferred:

   Authorization: Bearer mnt_sk_xxx
   

2. 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.

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:

1. Issue a new key.
2. Update the client configuration (Claude Desktop, Cursor, n8n).
3. Verify the new key works with a tools/list call.
4. 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 AI credits). New write tools are announced through the regular product release notes.