Connect an AI assistant

Last updated: 28 September 2026

What this is

Edition House publishes a remote Model Context Protocol server. An AI assistant that speaks MCP can connect to it, and the person who owns the Edition House account decides whether to allow that and what it may do.

Once connected, the assistant can answer questions about the search performance, Search Console and Google Analytics data and compliance findings of the businesses the person chose, and can queue an article draft for review. It acts as the person who authorised it, on those businesses only, and on nothing else.

Endpoint

https://www.edition.house/mcp

Transport is Streamable HTTP. The server is stateless: every request carries its own bearer token and no session id is issued. POST carries JSON-RPC. GET answers 405, because the server never initiates a message.

A request without a valid token answers 401 with a WWW-Authenticate header naming the protected-resource document, which is how a client discovers where to authorise.

Authorisation

OAuth 2.1 with PKCE (S256, required — there is no plain fallback and no implicit flow). Clients may register dynamically; no manual onboarding step is needed.

Discovery

GET /.well-known/oauth-protected-resource/mcp   (RFC 9728)
GET /.well-known/oauth-authorization-server     (RFC 8414)

Endpoints

POST /api/oauth/register    dynamic client registration (RFC 7591)
GET  /api/oauth/authorize   consent, then an authorization code
POST /api/oauth/token       code + PKCE verifier, or refresh
POST /api/oauth/revoke      revocation (RFC 7009)

The token endpoint takes application/x-www-form-urlencoded, as RFC 6749 requires. An access token lasts one hour; the refresh token rotates on every use and lasts sixty days.

Businesses and permissions

A person who belongs to several businesses ticks the ones the assistant may use; the business they had open starts ticked. The assistant loses a business the moment the person stops being a member of it. With more than one business, every tool call names one (business: its name, website or id from list_businesses); the server never guesses.

Five permissions, each its own checkbox on the consent screen so that reading and writing — and Google data — are never one decision:

content:read — tracked pages, their ranks, and the recommended next actions.
search:read — Google Search Console clicks, impressions, average positions and search queries.
analytics:read — Google Analytics visits, goal (key event) results and visits from AI assistants. Unticked unless the person ticks it.
compliance:read — open compliance findings, and checking supplied text against the regulator's rules.
content:write — queueing an article draft for review. Nothing is published.

A connection granted only the read permissions is not offered the write tool at all: tools/list returns what the grant can actually run, so an assistant cannot promise something that would then be refused.

Tools

Tool	Permission	What it does
`list_businesses`	any	Lists the businesses the connection covers. Every other tool takes a business argument naming one of them.
`list_pages`	content:read	Lists the pages Edition House tracks, each with its search rank for its target keyword and the market that rank was measured in.
`get_recommendations`	content:read	Returns the ranked queue of what to do next to existing pages — the same order the Edition House app shows.
`list_seo_experiments`	content:read	Every improvement Edition House made to a page, measured as an experiment: its stage, and once concluded its verdict and position change in the market it was measured in.
`get_search_performance`	search:read	Site-wide Search Console clicks, impressions and click-through rate, with the previous period — all countries and tracked markets as separate blocks.
`list_page_traffic`	search:read	Clicks, impressions, click-through rate and average position for each page, from the newest complete Search Console snapshot (all countries).
`get_page_movers`	search:read	The pages whose Search clicks rose or fell most between the two newest comparable snapshots.
`get_top_queries`	search:read	The searches that show the site, or one page, most — summed over the tracked markets or one named market.
`get_analytics_overview`	analytics:read	The main Google Analytics goal over the last 28 measured days against the 28 before, with Edition House's verdict, the top pages, other tracked goals and open goal alerts.
`list_page_analytics`	analytics:read	Google Analytics visits, goal events and goal rate for each landing page, each with its verdict.
`get_ai_assistant_traffic`	analytics:read	Visits from AI assistants such as ChatGPT, Perplexity and Gemini: the total, their share of all visits, and each assistant.
`list_compliance_issues`	compliance:read	Lists open compliance findings across web pages, LinkedIn posts and ads, with the phrase and the rule each one engages.
`check_text`	compliance:read	Checks supplied marketing copy against the business's regulator rules before it is published. The text is not stored.
`create_draft`	content:write	Adds an article to the Write queue as a draft for a person to review. It publishes nothing.

Every tool declares its read-only, destructive, idempotent and open-world hints. All but one are read-only; create_draft adds a draft and changes nothing that already exists.

What a connected assistant receives, and what it never does

Google Analytics data crosses only under analytics:read. Without that permission no visit count, goal count, goal rate or goal verdict is available to any tool, and the recommendation queue is served without its goal estimates. A tool result becomes prompt text inside the connected assistant, which is why the Privacy Policy (sections 4, 5.1 and 6.3) names this permission as one of the two places analytics data reaches an AI provider, and a test in the codebase holds every other tool to it.

Every figure travels with its scope and its dates. Search Console page and site traffic is all-country; search queries are summed over tracked markets; a position is an average over the window, never a rank. Google Analytics figures are visits, not Search Console clicks, and the two are never combined. A figure Edition House has not measured is reported as not measured, never as zero.

A connected assistant never receives another customer's data, or data about individual visitors. Every tool query is filtered to one business the person approved and still belongs to.

Limits and requirements

An Edition House account with a business already set up. A new account with no site connected has nothing to report.
check_text needs a regulator configured for the business. Without one it refuses and says so, rather than returning a clean result it cannot stand behind.
create_draft is bounded by the account's plan. When the allowance is spent, it refuses and queues nothing.
Registration is rate limited to sixty new clients per hour per address. A client registers once and reuses its client_id, so an integration never meets this; it exists because the endpoint has to be anonymous. Over the limit answers 429 with Retry-After.
Compliance findings are advisory. Edition House is not a law firm and a finding is a prompt to review, never a legal opinion.
Rank is reported for one named market at a time. Two markets are never merged into a single number.

Disconnecting

The person who authorised a connection can revoke it in Edition House settings, and the assistant stops working immediately for every business the connection covered. A client may also revoke its own tokens at /api/oauth/revoke.

Support

Email hello@edition.house. See also our Terms of Service and Privacy Policy.