MCP server

Tool reference

Every MCP tool, the inputs it takes and the gateway read or action it maps to.

Planned design

The MCP server described here is the planned design layered on top of the agency REST gateway, which is live today. Until the server ships, everything on this page can be done with the REST endpoints in the API section.

Tools come in two families. **Read tools** wrap GET ?resource=…&client_id=… and return rows plus a pagination cursor. **Action tools** wrap POST with an action field and either return a result or a job reference for work that runs in the background.

Read tools

Tool	Inputs	Returns
`list_clients`	`limit`, `cursor`	Clients the key can reach, with website and status.
`get_client`	`client_id`	One client record with its settings and connected integrations.
`list_keywords`	`client_id`, `limit`, `cursor`	Tracked keywords with volume, difficulty and intent.
`list_rankings`	`client_id`, `keyword`, `from`, `to`	Ranking history rows for charting or comparison.
`list_audits`	`client_id`, `limit`	Audit runs with score, issue counts and timestamps.
`get_audit_issues`	`client_id`, `audit_id`	Individual issues with severity, page and recommendation.
`list_backlinks`	`client_id`, `limit`, `cursor`	Referring domains with authority and first-seen date.
`list_citations`	`client_id`	Local directory listings and their accuracy status.
`list_articles`	`client_id`, `status`	Generated articles with status and deployment target.
`list_calls`	`client_id`, `from`, `to`	Tracked calls with source, transcript and lead grade.
`list_reports`	`client_id`	Generated client reports and share links.

Discoverability

The gateway ships a discovery endpoint listing every readable resource. The MCP server uses it at start-up, so new resources become available without a client update.

Action tools

Tool	Required inputs	Scope	Behaviour
`run_seo_audit`	`client_id`, `url`	`write`	Queues a crawl; returns an `audit_id` to poll.
`refresh_backlinks`	`client_id`	`write`	Refetches referring domains for the client.
`generate_keyword_ideas`	`client_id`, `seed`	`write`	Returns ideas with volume and difficulty.
`generate_topical_map`	`client_id`, `topic`	`write`	Builds a pillar-and-cluster content map.
`generate_article`	`client_id`, `keyword`	`write`	Drafts an article; returns an `article_id`.
`deploy_article`	`client_id`, `article_id`	`write`	Publishes to the connected site. Confirm first.
`optimize_page`	`client_id`, `url`	`write`	Returns on-page fixes for title, meta and headings.
`index_url`	`client_id`, `url`	`write`	Submits a URL for indexing.
`generate_press_release`	`client_id`, `topic`	`write`	Drafts a release for review.
`generate_gbp_post`	`client_id`, `topic`	`write`	Drafts a Google Business Profile post.
`run_local_grid_scan`	`client_id`, `keyword`	`write`	Runs a geo-grid rank scan around the location.
`analyze_llm_visibility`	`client_id`	`write`	Checks how assistants describe the brand.
`generate_outreach_email`	`client_id`, `prospect`	`write`	Drafts an outreach email. Does not send.
`send_prospect_email`	`client_id`, `email_id`	`write`	Sends a drafted email. Confirm first.

Shape of a tool call

json

{
  "name": "generate_article",
  "arguments": {
    "client_id": "c_8f21…",
    "keyword": "emergency dentist leeds",
    "word_count": 1400,
    "tone": "reassuring"
  }
}

Errors the assistant will see

Status	Meaning	What the assistant should do
400	Missing or invalid field	Ask you for the missing value; do not retry unchanged.
401	Bad or revoked key	Stop and report the auth failure.
403	Scope or client not permitted	Report the limit instead of trying another client.
429	Rate limited	Back off and retry with increasing delay.
500	Upstream job failure	Retry once, then report.