# MCP server

Ask your coding agent *"is my product recommended by ChatGPT for meeting scheduling?"* and let it find out. The recomention MCP server gives Claude Code, Cursor, Codex and other MCP clients tools to read rankings, start a report, wait for it, and read the result.

It is a thin client for the [JSON API](/) and holds no state. It uses the same [API key](/authentication/).

:::caution[Publishing soon]
The stdio server, `@recomention/mcp`, is **not on npm yet**, so the install commands below will fail with "not found" until it is published. Until then, everything the server does is available through the [JSON API](/guides/reports/) with the same key. The [changelog](/changelog/) will say when the package is listed.
:::

## Install (stdio) — once published

The server runs locally through `npx` and reads your key from its environment, so the key never passes through the model's context. Replace `rmk_…` with your key, and never commit a config that contains it.

### Claude Code

```bash
claude mcp add recomention \
  --env RECOMENTION_API_KEY=rmk_… \
  -- npx -y @recomention/mcp
```

### Cursor

`~/.cursor/mcp.json` (the same JSON works for most JSON-configured clients):

```json
{
  "mcpServers": {
    "recomention": {
      "command": "npx",
      "args": ["-y", "@recomention/mcp"],
      "env": { "RECOMENTION_API_KEY": "rmk_…" }
    }
  }
}
```

### Codex

`~/.codex/config.toml`:

```toml
[mcp_servers.recomention]
command = "npx"
args = ["-y", "@recomention/mcp"]
env = { RECOMENTION_API_KEY = "rmk_…" }
```

Restart or reload MCP servers, then ask the agent to call `recomention_rankings_list` to confirm it works.

### Environment

| Variable | | |
| --- | --- | --- |
| `RECOMENTION_API_KEY` | required for reports | From your account → Developers. Shown once. |
| `RECOMENTION_BASE_URL` | optional | Defaults to `https://api.recomention.com`. Leave it unset unless told otherwise. |
| `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `PERPLEXITY_API_KEY`, `GEMINI_API_KEY`, `XAI_API_KEY`, `DATAFORSEO_API_KEY` | optional | Only for `funding: "byok"`. See [Agent plan & your own keys](/agent-plan/). Read from the server's environment, never from a tool argument. |

### Or let the agent set itself up

Once the package is published, your account's Developers card shows a **Copy setup prompt** button. Paste the prompt into your agent and it installs the server and asks you for the key.

## Tools

| Tool | Cost | What it does |
| --- | --- | --- |
| `recomention_rankings_list` | free | List the public AI rankings. No key needed. |
| `recomention_rankings_get` | free | One ranking: who the engines name for a category, with counts. |
| `recomention_suggest_prompts` | free | Buyer questions worth checking, from templates. No model call. Never names the product. |
| `recomention_report_start` | **spends** | Start a report, funded by an agency credit or by your own provider keys. |
| `recomention_report_status` | free | Where a report is: queued, running, finished or failed. |
| `recomention_report_get` | free | A finished report as JSON: scores, competitors, sources, fix list, every answer. |
| `recomention_distribution_kit` | free | A finished report as Markdown files: where to get mentioned and a channel plan. |
| `recomention_reports_list` | free | Your reports, newest first. |

`recomention_report_start` is the only tool that spends anything. A well-behaved agent asks you before calling it and says which funding it will use; the skills below do.

## Skills

The package ships agent skills in the slash-command style. Copy a folder from its `skills/` directory into `.claude/skills/` (Claude Code) or your agent's equivalent:

- **`ai-visibility-check`** — check one product end to end: free rankings first, draft questions with you, confirm spend, start, wait, summarise honestly.
- **`fix-list-review`** — turn a finished report into a prioritised, honest plan of work.
- **`competitor-watch`** — compare who the engines name in a category, from public rankings and your reports.
- **`distribution-kit`** — read a finished report's kit and work through its channel plan, one channel at a time.

## Hosted MCP — coming soon

A hosted server is planned, so you can connect without running anything locally:

```text
https://mcp.recomention.com/mcp
```

It will speak Streamable HTTP and authenticate with the same API key as a Bearer token. It is not live yet; use the stdio server above until the [changelog](/changelog/) announces it.