MCP tool reference

Connection and access

Server URL: https://mcp.seoresearcher.ai/mcp. Transport: Streamable HTTP. Permissions: seo_research:read and seo_research:run. OAuth is the default setup route. API-key access requires an appropriately scoped credential; a skill does not create one.

seo_research_connection

No inputs. Reports the authenticated organization_id, existing default_client_id (or null), granted research scopes, and metering_model. Use this before listing jobs when you need to confirm which account is connected. These are account identifiers, not the name or email of the person signed in. A null workspace means none exists yet; the first explicitly requested research job can create it. A successful connection does not prove that research has completed or that unused capacity remains.

This check does not start research or create a workspace. If the tool is missing after an update, refresh your client’s tool list or reconnect the existing connector.

seo_research_usage

No inputs. Reports the current plan, included, used, reserved, remaining, and overage units, active concurrency, warning state, and secure billing URL. It is read-only and does not consume a research unit. Agents should call it before a large batch and after an allowance warning.

If the allowance is exhausted, seo_research_start returns a non-retryable upgrade response with the same secure billing URL. Upgrading changes the connected account immediately; the MCP connection does not need to be reauthorized.

seo_research_start

Starts research and returns a saved job to follow. Research can consume your included usage and invoke research providers.

{
  "topic": "best CRM for solo consultants",
  "country": "United States",
  "language": "en",
  "depth": "standard",
  "idempotency_key": "consultant-crm-brief-2026-09-04-01"
}

The key above is illustrative. Create a distinct key for each new intentional job; reuse it only for retries of the same request. Do not invent workspace IDs. Do not send confidential customer details in the topic or idempotency key.

seo_research_status

Input: job_id, the UUID returned by start. Read its actual state, stage, quality information, and polling guidance. Poll at recommended_poll_seconds (in seconds) when supplied. Terminal failure is not successful research. Avoid guessing a job ID or restarting work because it is still running.

seo_research_get

Inputs: job_id and view (summary, full, or evidence; default full). Retrieve after completion. Use summary for orientation, full for detailed briefs and drafting, and evidence to inspect retained source support. A partial-quality packet still requires explicit limitations; missing sources are not zero competition.

seo_research_list

Inputs: limit (integer 1–100, default 20) and optional cursor (up to 500 characters). Use this to find recent saved jobs, recover a job ID, or test authenticated access without starting research. MCP list responses also include connection metadata identifying the authenticated account, even when the job list is empty.

A reliable sequence

1. Reuse a suitable existing packet when available, checking freshness and market fit.
2. Start one requested job and save its ID and idempotency key.
3. Poll that same job at the returned interval. If no interval is returned, wait at least 10 seconds. After ten minutes without completion, retain the ID and report the last state; this is a client workflow limit, not a service completion promise.
4. Read the completed result and disclose unavailable evidence.
5. Draft or edit using the agent’s own writing capabilities and your instructions.

The MCP does not publish, write articles, measure your traffic, or automatically verify every source claim. Those steps require other tools and evidence.

REST equivalents

Base URL: https://api.seoresearcher.ai.

Use a scoped bearer credential in the Authorization header. Preserve idempotency with the Idempotency-Key header on retries. Never put credentials in URLs. These are API paths for integrations, not URLs to paste into an MCP server field.