MCP Connection Guide — SERP Checker

1

Get an API Key

All MCP requests require the same named API key used for the REST API.

Ask a workspace admin to create an API key for your integration. The raw key is shown only once and is required for every MCP request.

Store the key securely. If lost, delete it and create a new one.

2

Configure your MCP client

Edit your desktop MCP client configuration file (Mac/Linux) or %APPDATA%\...\desktop_config.json (Windows):

json

{
  "mcpServers": {
    "serp-checker": {
      "type": "streamable-http",
      "url": "https://serp.tsoden.ai/mcp",
      "headers": {
        "Authorization": "Bearer sk-YOUR_API_KEY"
      }
    }
  }
}

Restart the desktop client. You will see SERP Checker tools in the MCP tool list.

Open Cursor Settings → MCP and add a new server:

json

{
  "serp-checker": {
    "transport": "streamable-http",
    "url": "https://serp.tsoden.ai/mcp",
    "headers": {
      "Authorization": "Bearer sk-YOUR_API_KEY"
    }
  }
}

Or paste this into .cursor/mcp.json at the workspace root for per-project configuration.

In an n8n workflow use the MCP Client node (or HTTP Request node) with the following settings:

Field	Value
Transport	Streamable HTTP
URL	`https://serp.tsoden.ai/mcp`
Header name	`Authorization`
Header value	`Bearer sk-YOUR_API_KEY`

Send a tools/list call to verify connectivity, then use tools/call with any tool name from the list below.

Using the official mcp Python package:

python

import asyncio
import httpx2
from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client

API_KEY = "sk-YOUR_API_KEY"
MCP_URL = "https://serp.tsoden.ai/mcp"

async def main():
    http_client = httpx2.AsyncClient(
        headers={"Authorization": f"Bearer {API_KEY}"},
        timeout=60,
    )
    async with streamable_http_client(MCP_URL, http_client=http_client) as streams:
        read, write = streams[0], streams[1]
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()
            print([t.name for t in tools.tools])

            # Start a SERP check for client 1
            result = await session.call_tool(
                "start_serp_check", {"client_id": 1}
            )
            print(result.content)

asyncio.run(main())

Install: pip install mcp — this example targets the mcp 2.x SDK. On mcp 1.x the import is streamablehttp_client and headers are passed directly to it.

initialize

bash

curl -s -X POST https://serp.tsoden.ai/mcp \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0", "id": 1, "method": "initialize",
    "params": {
      "protocolVersion": "2025-11-25",
      "clientInfo": {"name": "curl-test", "version": "1.0"},
      "capabilities": {}
    }
  }'

tools/list

bash

curl -s -X POST https://serp.tsoden.ai/mcp \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}'

tools/call — list_clients

bash

curl -s -X POST https://serp.tsoden.ai/mcp \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0", "id": 3, "method": "tools/call",
    "params": {"name": "list_clients", "arguments": {}}
  }'

tools/call — start_serp_check

bash

curl -s -X POST https://serp.tsoden.ai/mcp \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0", "id": 4, "method": "tools/call",
    "params": {"name": "start_serp_check", "arguments": {"client_id": 1}}
  }'

3

Available MCP Tools

Tool name	Description	Required args
list_clients	List all clients visible to your API key.	—
get_client	Return one client with keywords and competitors.	`client_id`
create_client	Create a new client/site record.	`name, domain`
list_keywords	List keywords for a client.	`client_id`
add_keywords	Add one or more keywords to a client (with lang/geo/device/intent).	`client_id, keywords[]`
list_competitors	List competitor domains for a client.	`client_id`
add_competitor	Add a competitor domain to a client.	`client_id, domain`
list_jobs	List SERP check jobs, optionally filtered by client.	—
get_job	Return status and results for one SERP check job.	`job_id`
start_serp_check	Enqueue a SERP rank check for all keywords of a client.	`client_id`
serp_search	Run an ad-hoc Google SERP search (Serper-compatible).	`q`
list_analytics_reports	List uploaded GA/GSC analytics reports.	—
get_analytics_report	Get one analytics report with saved analysis.	`report_id`
list_api_keys	List your named API keys (no raw values returned).	—
create_api_key	Create a named API key (raw key returned once).	—
delete_api_key	Delete one of your API keys.	`key_id`
get_ai_visibility_overview	One-call AEO overview: which prompts trigger AEO answers, plus whether past recommendations moved visibility. Best first call before planning AEO work.	`client_id`
read_openapi_spec	Return the current OpenAPI specification document.	—
api_request	Generic escape hatch — call any REST endpoint by method + path.	`method, path`
rest_*	Auto-generated tools for every API-key-authenticated OpenAPI operation, including client, keyword, competitor, job, analytics, indexing, learning, ASO, and SERP endpoints.	Defined by each operation schema

The hand-written tools cover common integration workflows. The generated rest_* tools mirror the live Swagger/OpenAPI document so MCP clients can use the complete REST API surface without waiting for a custom tool wrapper.

ASO via generated REST tools

json

{
  "jsonrpc": "2.0",
  "id": 21,
  "method": "tools/call",
  "params": {
    "name": "rest_listAsoApps",
    "arguments": {"client_id": 1}
  }
}

json

{
  "jsonrpc": "2.0",
  "id": 22,
  "method": "tools/call",
  "params": {
    "name": "rest_addAsoKeywords",
    "arguments": {
      "client_id": 1,
      "body": [
        {"query": "ai stylist", "store": "app_store", "country": "GB", "language": "en"}
      ]
    }
  }
}

json

{
  "jsonrpc": "2.0",
  "id": 23,
  "method": "tools/call",
  "params": {
    "name": "rest_runAsoListingAudit",
    "arguments": {
      "client_id": 1,
      "body": {"store": "app_store", "max_apps": 1}
    }
  }
}

json

{
  "jsonrpc": "2.0",
  "id": 24,
  "method": "tools/call",
  "params": {
    "name": "rest_runAsoFullRefresh",
    "arguments": {
      "client_id": 1,
      "body": {"store": "app_store", "max_apps": 1, "max_keywords": 25, "limit": 25}
    }
  }
}

4

MCP Prompts & Resource Templates

Built-in prompts (prompts/list)

Prompt	Description	Args
seo_visibility_analysis	Analyze rankings, movers, opportunities for one client.	`client_id`
serp_check_workflow	Plan a SERP check run and follow-up inspection.	`client_id`
api_integration_help	Explain how to connect via REST or MCP.	—

Resource URI templates (resources/templates/list)

URI template	Description
serp://clients/{client_id}	Client record with keywords and competitors.
serp://clients/{client_id}/keywords	Keyword set for one client.
serp://clients/{client_id}/competitors	Competitor domains for one client.
serp://jobs/{job_id}	Status and results for one SERP check job.
serp://analytics-reports/{report_id}	Uploaded analytics report and saved analysis.

5

Example response: tools/call list_clients

json

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"status\": 200,\n  \"headers\": {\"Content-Type\": \"application/json\"},\n  \"body\": [{\"id\": 1, \"name\": \"Example Store\", \"domain\": \"example.com\", \"keyword_count\": 142}, ...]\n}"
      }
    ],
    "isError": false,
    "structuredContent": {
      "status": 200,
      "headers": {"Content-Type": "application/json"},
      "body": [{"id": 1, "name": "Example Store", "domain": "example.com", "keyword_count": 142}]
    }
  }
}