All documentation

    Agent integrations (MCP server)

    Rank Pilot AI SEO exposes a read-only Model Context Protocol (MCP) server, defined in src/lib/mcp, so that external AI agents and MCP-compatible clients can query a signed-in user's own SEO data on their behalf, with the same access boundaries as the rest of the platform.

    Server definition

    The server is declared in src/lib/mcp/index.ts using defineMcp from @lovable.dev/mcp-js:

    • Identity — named rank-pilot-mcp, titled "Rank Pilot AI SEO", with instructions telling a connecting agent to call list_websites first to discover a website id, then use that id with the other tools.
    • Authentication — configured as an OAuth resource server (auth.oauth.issuer) whose issuer is the Supabase Auth endpoint for the project, accepting only tokens whose audience is authenticated. This means the MCP server does not run its own login system; it validates the same Supabase-issued access tokens used everywhere else in the app, so an MCP client must complete the standard OAuth consent flow (below) to obtain a token before any tool call is authorised.
    • Tools — a fixed list of five read-only tools, each in its own file under src/lib/mcp/tools/.

    Available tools

    All tools are defined with defineTool and annotated readOnlyHint: true, idempotentHint: true, openWorldHint: false — they only read data, calling them repeatedly has no side effects, and they don't reach outside the user's own Supabase data. Each tool builds a Supabase client scoped to the calling agent's bearer token (ctx.getToken()), so every query runs under the connecting user's own identity and is subject to the same Row Level Security policies as the web app — there is no service-role escape hatch here, and an agent can never see data belonging to a different user.

    • list_websites — lists the websites tracked in the signed-in user's account (id, name, URL, creation date). This is the entry point every agent session is instructed to call first, since the other tools operate on a specific website id.
    • list_keywords — lists the keywords tracked for a given website.
    • get_keyword_rankings — returns ranking data/history for a specific keyword (or set of keywords) on a website, mirroring what the rank-tracking dashboard shows.
    • get_site_audit — returns the most recent technical SEO audit findings for a website.
    • list_backlinks — lists tracked backlinks for a website.

    Each tool validates its input with zod, checks ctx.isAuthenticated() before doing any work and returns an explicit error response rather than throwing if the caller isn't authenticated, and returns results both as human-readable text content and as structuredContent so that MCP clients can consume the data programmatically as well as display it.

    OAuth consent flow

    Because the MCP server is an OAuth resource server backed by Supabase Auth, connecting an external agent client involves an authorisation step the user explicitly approves, rendered by the app itself rather than a third-party page:

    • The consent screen is served at the route /.lovable/oauth/consent, defined in src/routes/[.]lovable.oauth.consent.tsx. The bracketed filename escapes the leading dot/segment so the file-based router treats .lovable as a literal path segment rather than special routing syntax.
    • The route renders the OAuthConsent page component (src/pages), which is where the signed-in user reviews the connecting client's request and approves or denies it.
    • On approval, the standard OAuth authorisation-code exchange completes against the Supabase Auth issuer configured in the MCP server definition, and the connecting agent receives an access token scoped to the authenticated audience — the same class of token issued to the web app itself.
    • From that point on, every tool call the agent makes carries that token; the MCP server validates it against the configured issuer/audience before invoking a tool, and the tool's own Supabase client (built per-request from that token) enforces RLS exactly as it would for a browser session, so the consent step is what stands between "an agent claims to act for this user" and "an agent can actually read this user's websites, keywords, audits and backlinks."

    Design intent

    The MCP integration is deliberately narrow: it is read-only, limited to five SEO-domain tools, and has no path to mutate data, manage billing, change account settings or access another user's records. This keeps the "agent surface" of the platform auditable and bounded — an agent can help a user reason about their own rankings, audits and backlinks, but cannot take actions, spend the user's credits, or reach data outside what RLS already permits that user to see through the web app.