— Developers · MCP

MCP server.

Give Claude, Cursor or an n8n agent eleven SeoPrimo tools: they read your sites, start audits and analyses and tell you the price before spending credits.

ready tools

HTTP

Streamable, no sessions

Bearer

the same key as the API

— Connection

One endpoint, one key.

Endpoint: https://seoprimo.it/mcp
Transport: Streamable HTTP, stateless. Every request is a JSON-RPC POST answered with application/json; there are no sessions and the server-to-client channel (GET) answers 405.
Authentication: Authorization: Bearer sp_live_… on every request, with the same key as the REST API. Create the key in Integrations, API keys.
Protocol versions: 2025-06-18 and 2025-03-26.
Limit: 60 requests per minute per key, the same count as the REST API.
Scopes: every tool checks the key's scope for the requested action (read to read, write to start). A read-only key can only use the read actions.

— Setup

Connect your client.

Replace sp_live_... with your key. If the client allows it, keep it in an environment variable and not in the file.

Claude Desktop

Claude Desktop opens remote servers through mcp-remote. Add this to claude_desktop_config.json and restart the app. The header goes through an environment variable because spaces in arguments cause problems on Windows.

JSON

{
  "mcpServers": {
    "seoprimo": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://seoprimo.it/mcp",
        "--transport",
        "http-only",
        "--header",
        "Authorization:${SEOPRIMO_AUTH}"
      ],
      "env": {
        "SEOPRIMO_AUTH": "Bearer sp_live_..."
      }
    }
  }
}

Claude Code

shell

claude mcp add --transport http seoprimo https://seoprimo.it/mcp --header "Authorization: Bearer sp_live_..."

Then, inside Claude Code, /mcp shows the SeoPrimo tools.

Cursor

In ~/.cursor/mcp.json (or the project file, .cursor/mcp.json):

JSON

{
  "mcpServers": {
    "seoprimo": {
      "url": "https://seoprimo.it/mcp",
      "headers": {
        "Authorization": "Bearer sp_live_..."
      }
    }
  }
}

n8n

In the MCP Client Tool node of an AI Agent: Endpoint = https://seoprimo.it/mcp, HTTP Streamable transport, Header Auth authentication with the "SeoPrimo API" credential. The full steps are in the n8n guide.

— Tools

The eleven tools.

Each tool has an action chosen by a parameter, so the tools stay few and the agent does not get lost. All paid tools accept dry_run: true.

The eleven tools of the MCP server
Tool	What it does	Key parameters	Scope	Credits
`seoprimo_sites`	Lists the account's sites or adds one. Every other tool starts from a site_id from here.	`action: list \| add`	`read` for list, `write` for add	Free
`seoprimo_audit`	Quick audit (Score, five pillars, summary) or full audit (crawl with the data engine). The full audit is a long job: follow it with action=status and the run_id you get back.	`mode: quick \| full · action: start \| status`	`write` for start, `read` for status	Quick: 10 credits (given back if it fails). Full: crawl from 2 credits (1 per 100 pages), Lighthouse extra
`seoprimo_keywords`	Keyword ideas from seeds, or volume, difficulty, CPC and intent of a list.	`action: research \| metrics`	`write`	Credits
`seoprimo_rankings`	Google rank tracking: list, create, check now (long job) and read the outcome.	`action: list \| create \| run \| status`	`read` for list and status, `write` for create and run	Creating is free, every check is in credits
`seoprimo_backlinks`	Backlinks of the site or of another domain: overview or paginated profile.	`action: overview \| profile`	`write`	Credits
`seoprimo_competitors`	The domains competing with the site on the given keywords.	-	`write`	Credits
`seoprimo_ai_visibility`	Whether ChatGPT and Google AI Overview mention the brand. One run per platform.	-	`write`	Credits, per platform
`seoprimo_agent`	Starts an AI agent on the site (analisi_completa or report_mensile) and reads its diary and report. The agent works for a few minutes: follow it with action=status and the run_id you get back.	`action: start \| status · agent · budget_credits`	`write` for start, `read` for status	Up to budget_credits (300 full analysis, 150 monthly report)
`seoprimo_score`	The latest full SeoPrimo Score (pillars, checks) and the last 12 measurements.	-	`read`	Free
`seoprimo_report`	The site's HTML reports: list them or read one.	`action: list \| get`	`read`	Free
`seoprimo_credits`	The credit balance and the buckets they are consumed from.	-	`read`	Free

— Credits and safety

An agent that does not surprise.

The price first. With dry_run: true a paid tool answers with the estimate and spends nothing. In the agent's instructions tell it to always call dry_run first and to ask you for confirmation above a threshold.
No tool deletes. There is no tool to delete sites or keys: the agent can add sites and spend credits, not destroy data.
Readable errors. Out of credits, unknown site or missing scope come back as a tool result with isError: true: the agent reads them and adapts. Protocol errors (invalid key, limit exceeded) carry the HTTP status and the API's error code.
One key per agent. Give each agent its own key, with only the scope it needs: you revoke it without touching the others.
If you call it from a browser, the Origin header must be https://seoprimo.it: other origins get 403. Command-line, editor and server clients send no Origin and are not affected.

— Try it

From the command line.

To check the key and the endpoint without an MCP client you can speak JSON-RPC with curl: initialize, then tools/list, then a tool call.

curl

export SEOPRIMO_KEY="sp_live_..."

# 1. initialize
curl -sS https://seoprimo.it/mcp \
  -H "Authorization: Bearer $SEOPRIMO_KEY" \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize",
       "params": {"protocolVersion": "2025-06-18", "capabilities": {},
                  "clientInfo": {"name": "curl", "version": "1.0"}}}'

# 2. list the tools
curl -sS https://seoprimo.it/mcp \
  -H "Authorization: Bearer $SEOPRIMO_KEY" -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'

# 3. call a tool (your credit balance)
curl -sS https://seoprimo.it/mcp \
  -H "Authorization: Bearer $SEOPRIMO_KEY" -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 3, "method": "tools/call",
       "params": {"name": "seoprimo_credits", "arguments": {}}}'

Agents at work

Ten tools,
your agent.

Create a key, paste it into your client's configuration and ask: "run a quick audit of my site".

Create an API key Use n8n

What the guide gives you

Key from the panel

read and write scopes

Client configuration

Claude, Cursor, n8n

Available tools

dry_run on credit tools