@mencoro/mcp

Mencoro MCP server

Ask an AI assistant how your brand is doing in AI answers — rank, mentions, sentiment and Share of Voice — in plain language.

Mencoro tracks how brands surface in AI answer engines — ChatGPT, Perplexity, Google AI Overview and AI Mode — and in Google Search and Shopping. The MCP server exposes that data to any MCP client as 17 read-only tools and 12 prompts.

The server is hosted. Most clients should connect to it directly:

https://api.mencoro.com/mcp

This repository holds the public metadata for that server plus a small stdio bridge (@mencoro/mcp) for hosts that can only launch a local process. It does not contain the Mencoro application source.

Connect

Clients that speak remote MCP (recommended)

No install, no local process. Sign in with OAuth, or paste a personal access token as a header.

Client	How
Claude (web, Desktop, mobile)	Settings → Connectors → Add custom connector → paste the URL → Sign in. Or use the one-click link.
ChatGPT	Settings → Apps & Connectors → developer mode → add the URL → sign in.
Claude Code	claude mcp add --transport http mencoro https://api.mencoro.com/mcp then /mcp to sign in
Cursor	config below
VS Code	config below
OpenAI Codex	config below
Gemini CLI	config below
OpenCode	config below
Google Antigravity	config below

Clients that can only spawn a local process

Claude Desktop's manual configuration, and older stdio-only hosts, need a bridge. That is what this package is:

npx -y @mencoro/mcp

// claude_desktop_config.json
{
  "mcpServers": {
    "mencoro": {
      "command": "npx",
      "args": ["-y", "@mencoro/mcp"],
      "env": { "MENCORO_API_KEY": "mcp_pat_your_token" }
    }
  }
}

The token goes through the environment rather than an argument, so it does not appear in ps output and does not have to survive the host's argument splitting.

Authentication

Two ways in. Both give the same read-only access.

OAuth 2.1 — the one-click path. Supported by Claude, ChatGPT, Claude Code and any client that implements the MCP authorization spec. Nothing to copy or paste; revoke it from the app. The server advertises PKCE (S256), Client ID Metadata Documents, Dynamic Client Registration and RFC 9728 resource metadata, so clients discover everything they need from https://api.mencoro.com/.well-known/oauth-protected-resource/mcp.

Personal access token — for CLI clients, config files, and this bridge. Create one at tool.mencoro.com/me/mcp-server; it is shown once, starts with mcp_pat_, is read-only, and can be scoped to a single organization and given an expiry. Send it as Authorization: Bearer mcp_pat_….

ChatGPT cannot send a custom Authorization header to a remote connector — use OAuth there.

Client configuration

Cursor — ~/.cursor/mcp.json

{
  "mcpServers": {
    "mencoro": {
      "url": "https://api.mencoro.com/mcp",
      "headers": { "Authorization": "Bearer mcp_pat_your_token" }
    }
  }
}

VS Code — .vscode/mcp.json

{
  "servers": {
    "mencoro": {
      "type": "http",
      "url": "https://api.mencoro.com/mcp",
      "headers": { "Authorization": "Bearer mcp_pat_your_token" }
    }
  }
}

OpenAI Codex — ~/.codex/config.toml

[mcp_servers.mencoro]
url = "https://api.mencoro.com/mcp"
http_headers = { "Authorization" = "Bearer mcp_pat_your_token" }

Gemini CLI — ~/.gemini/settings.json

{
  "mcpServers": {
    "mencoro": {
      "httpUrl": "https://api.mencoro.com/mcp",
      "headers": { "Authorization": "Bearer mcp_pat_your_token" }
    }
  }
}

OpenCode — opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mencoro": {
      "type": "remote",
      "url": "https://api.mencoro.com/mcp",
      "enabled": true,
      "headers": { "Authorization": "Bearer mcp_pat_your_token" },
      "oauth": false
    }
  }
}

oauth: false stops OpenCode negotiating OAuth against an endpoint that also advertises it, which would otherwise override the token you just configured.

Google Antigravity

{
  "mcpServers": {
    "mencoro": {
      "serverUrl": "https://api.mencoro.com/mcp",
      "headers": { "Authorization": "Bearer mcp_pat_your_token" }
    }
  }
}

Claude Code — project scope, committed to a repository

{
  "mcpServers": {
    "mencoro": {
      "type": "http",
      "url": "https://api.mencoro.com/mcp",
      "headers": { "Authorization": "Bearer ${MENCORO_API_KEY}" }
    }
  }
}

Tools

All 17 are read-only. Nothing in this server can change a project, a tracked query or a setting.

Tool	What it answers
list_projects	The organizations and active projects you can see. Call this first — every other tool needs the ids it returns.
get_available_filters	Which engines, countries, keyword clusters and competitors a project actually has.
get_metric_glossary	Maps everyday wording ("visibility", "tone", "ranking") onto the right metric and tool.
get_organization_overview	Current-state board across every active project in an organization, ranked by Share of Voice.
get_project_rank_tracking_stats	The project summary: positions, trends, Share of Voice per competitor, sentiment split, mention/SERP/shopping rates.
get_rank_tracking_time_series	Those metrics over time, bucketed daily, weekly or monthly, optionally per competitor.
get_tracked_query_time_series	The same history for one tracked query.
get_query_movers	The tracked queries that gained or lost the most versus the previous period.
get_cluster_breakdown	The same metrics broken down per keyword cluster.
search_tracked_queries	Search and paginate a project's tracked queries with their latest positions.
get_sentiment_breakdown	Positive / neutral / negative split of your AI mentions, per engine and per competitor.
get_mention_mix	Mention counts by type, tone and qualifier — the inputs behind the Share of Voice weighting.
get_mention_samples	The raw AI mention texts, paginated and filterable, for qualitative review.
get_competitor_cooccurrence	Head-to-head: when you and a competitor appear in the same answer, who is named higher.
get_cited_sources	The domains and pages the answer engines cited, with counts and average citation rank.
get_tracking_coverage	What is stale: paused, never-checked and overdue tracked queries.
get_share_of_voice_formula	The weights and multipliers the Share of Voice score is built from.

Dates are ISO YYYY-MM-DD and must fall inside the retention window. Positions are 1-based and lower is better; every other metric improves as it rises.

Prompts

Twelve ready-made questions, surfaced by clients that support MCP prompts:

brand_ai_overview · whats_changed · organization_overview · top_queries · biggest_movers · query_history · competitor_standing · head_to_head · negative_mentions · cited_sources · coverage_health · sov_explainer

The bridge

Run it

export MENCORO_API_KEY=mcp_pat_your_token
npx -y @mencoro/mcp            # serve on stdio
npx -y @mencoro/mcp doctor     # check the endpoint, the token, and list the tools

Docker

docker run --rm -i -e MENCORO_API_KEY=mcp_pat_your_token ghcr.io/mencoro/mencoro-mcp

-i is required and -t must be omitted: the MCP transport is this process's stdin and stdout.

Options

MENCORO_API_KEY	Personal access token. Without it the bridge starts anyway and serves a single mencoro_setup tool explaining how to get one.
MENCORO_MCP_URL	Upstream endpoint. Defaults to https://api.mencoro.com/mcp.
--url <url>	Same, as an argument.
--header "Name: value"	Extra HTTP header, repeatable. An Authorization header here overrides MENCORO_API_KEY.
doctor	Connect once, print the server version, negotiated protocol, tool and prompt catalogue, then exit.
--help, --version

What it actually does

It splices your client's stdio transport onto a Streamable HTTP transport and forwards every JSON-RPC frame verbatim, in both directions. The only frame it looks inside is the handshake — enough to echo the negotiated protocol version back upstream and to rebuild the session if the server evicts it, which a deploy or a scale-down will do. It knows no other method, so it cannot drift from the server: tools, prompts, resources, completions, progress notifications and anything added later all pass straight through.

Limits

Access	Read-only. 17 tools, no mutations.
Retention	Up to 16 months of history; dates outside the window are rejected.
Transport	Streamable HTTP.
Rate limiting	Repeatedly presenting an invalid credential is rate limited per IP.
Result size	Large result sets are paginated; ask for a narrower window or a coarser granularity if a client truncates.

Repository contents

src/, test/	The stdio bridge published as @mencoro/mcp.
server.json	The MCP registry manifest.
glama.json	Glama directory ownership metadata.
Dockerfile	The image published to ghcr.io/mencoro/mencoro-mcp.
assets/, logo.png	Brand assets used by directory listings.

Development

npm ci
npm run typecheck
npm test            # builds first, then runs the suite
npm run check:manifests

Tests run the TypeScript sources directly through Node's type stripping, so development needs Node 22.18 or newer. The published package targets Node 20.19+, which CI verifies separately against the built artifact.

Releases are cut by tagging. npm version <patch|minor|major>, mirror the new version into server.json (.version, the npm package entry, and the image tag), run npm run check:manifests, then push the tag — CI publishes to npm, GHCR and the MCP registry, in that order.

Support

• Product and account questions — [e-mail]
• Bugs in this package — open an issue
• Security — see SECURITY.md
• About the server — mencoro.com/features/mcp-server

Licence

MIT. See LICENSE.

The Mencoro name, logo and brand assets in assets/ are trademarks of Mencoro and are not covered by that licence.