How to Use OpenSEO MCP for Site Audits: A Complete Technical Guide

OpenSEO MCP exposes a JSON-RPC interface that lets AI agents and developers launch Cloudflare-powered site audits via the run_site_audit method, monitor progress with get_audit_status, and retrieve prioritized SEO issues and Lighthouse data through dedicated endpoints.

The every-app/open-seo repository provides a Model-Context Protocol (MCP) server that transforms any compatible AI client into a technical SEO auditing engine. By leveraging OpenSEO MCP for site audits, you can programmatically crawl websites, detect on-page issues, and generate performance reports without managing crawler infrastructure or storage systems.

Architecture Overview

The OpenSEO MCP implementation follows a distributed serverless architecture built on Cloudflare's edge platform. Understanding these components helps you debug issues and optimize your integration.

MCP Server Endpoint
The server runs as a Cloudflare Worker exposed at the /mcp route, defined in the global configuration at worker-configuration.d.ts. It authenticates requests using signed JWT tokens and enforces rate limits through the MCP_RATE_LIMIT environment variable.

Site-Audit Tools
Located in src/server/mcp/tools/site-audit-tools.ts, this module registers four JSON-RPC methods: run_site_audit, get_audit_status, get_audit_issues, and get_audit_pages. Each method validates parameters, checks subscription tiers, and interacts with the underlying workflow engine.

Site-Audit Workflow
src/server/workflows/SiteAuditWorkflow.ts executes the actual crawl. This Cloudflare Workflow respects robots.txt, follows same-origin links, records per-page SEO metrics (title, description, canonical, word count), and optionally launches Lighthouse for performance scoring.

Data Persistence
Audit state lives in Cloudflare D1 tables (audit, audit_page) accessed through src/server/features/audit/repositories/AuditRepository.ts. This abstraction layer handles reads and writes for status updates, issue storage, and page-level metadata retrieval.

Access Control
The AuditService.ts file enforces subscription checks using the PAYMENT_REQUIRED constant. Free-tier plans are limited to 50 pages per crawl, while paid subscriptions unlock larger crawls and advanced features.

Setting Up the MCP Connection

Before invoking audit commands, you must establish an authenticated connection to the MCP endpoint.

Endpoint Options
You can either self-host the Cloudflare Worker by running pnpm run deploy in the repository, or use the hosted instance at https://app.openseo.so/mcp.

Authentication
Generate an API token in the OpenSEO web interface under Settings → API Keys. All MCP requests require this token in the Authorization header as a Bearer token.

curl -X POST https://app.openseo.so/mcp \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
        "jsonrpc":"2.0",
        "method":"run_site_audit",
        "params":{"url":"https://example.com","lighthouse":false,"maxPages":50},
        "id":1
      }'

Executing a Site Audit

The audit lifecycle involves three distinct phases: initiation, monitoring, and result retrieval. Each phase corresponds to a specific MCP tool method.

Starting the Crawl

Invoke the run_site_audit method with your target URL and optional configuration flags. The method immediately returns an auditId that you will use for all subsequent operations.

Key Parameters:

• url: The starting URL for the crawl (must include protocol)
• lighthouse: Boolean flag to enable Lighthouse performance auditing
• maxPages: Maximum URLs to crawl (capped at 50 for free plans)

curl -X POST https://app.openseo.so/mcp \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
        "jsonrpc":"2.0",
        "method":"run_site_audit",
        "params":{
          "url":"https://example.com",
          "lighthouse":true,
          "maxPages":50
        },
        "id":1
      }'

Example Response:

{
  "jsonrpc":"2.0",
  "result":{"auditId":"a1b2c3d4"},
  "id":1
}

Monitoring Progress

Poll the get_audit_status method using your auditId to track the audit through its lifecycle phases. Valid phase values include queued, crawling, completed, and failed.

The workflow queues jobs asynchronously, so implement exponential backoff or fixed-interval polling (every 2-5 seconds) to check completion status without hitting MCP_RATE_LIMIT thresholds.

async function pollAuditStatus(auditId, token) {
  while (true) {
    const response = await fetch('https://app.openseo.so/mcp', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        jsonrpc: '2.0',
        method: 'get_audit_status',
        params: { auditId },
        id: 2
      })
    });
    
    const { result } = await response.json();
    console.log('Current phase:', result.phase);
    
    if (result.phase === 'completed' || result.phase === 'failed') {
      return result;
    }
    
    await new Promise(resolve => setTimeout(resolve, 2000));
  }
}

Retrieving Results

Once the phase reaches completed, fetch the findings using two complementary methods.

Get Prioritized Issues
The get_audit_issues method returns an array of detected SEO problems, each including a how_to_fix field suitable for AI agent consumption or direct user display.

curl -X POST https://app.openseo.so/mcp \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
        "jsonrpc":"2.0",
        "method":"get_audit_issues",
        "params":{"auditId":"a1b2c3d4"},
        "id":3
      }'

Get Per-Page Data
The get_audit_pages method returns granular data for every crawled URL, including HTTP status, title tags, meta descriptions, canonical links, word counts, and Lighthouse scores (if enabled during initiation).

curl -X POST https://app.openseo.so/mcp \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
        "jsonrpc":"2.0",
        "method":"get_audit_pages",
        "params":{"auditId":"a1b2c3d4"},
        "id":4
      }'

Key Configuration and Limitations

When implementing OpenSEO MCP for site audits in production environments, consider these technical constraints and capabilities defined in the source code.

Rate Limiting
The MCP_RATE_LIMIT configuration in worker-configuration.d.ts governs request throughput. Exceeding these limits returns standard HTTP 429 responses, requiring client-side retry logic with exponential backoff.

Crawl Scope
The SiteAuditWorkflow.ts crawler strictly follows same-origin links. It will not follow external domains or subdomains unless they share the same origin as the initial url parameter.

Robots.txt Compliance
The workflow automatically fetches and respects robots.txt directives before crawling any path. URLs blocked by robots directives are skipped and recorded in the audit log with a specific exclusion reason.

Storage Schema
The AuditRepository.ts layer writes to two primary D1 tables: the audit table stores high-level metadata (status, URL, timestamp), while audit_page contains individual page records indexed by auditId.

Summary

• OpenSEO MCP exposes site auditing capabilities through a Cloudflare Worker implementing the Model-Context Protocol specification.
• Four JSON-RPC methods control the audit lifecycle: run_site_audit, get_audit_status, get_audit_issues, and get_audit_pages defined in src/server/mcp/tools/site-audit-tools.ts.
• Authentication requires a Bearer token derived from your OpenSEO API key, sent with every request to the /mcp endpoint.
• Free-tier limits restrict crawls to 50 pages per audit, enforced by AuditService.ts using the PAYMENT_REQUIRED check.
• Lighthouse integration is optional and controlled via the lighthouse boolean parameter in the initial request.
• Data persistence uses Cloudflare D1 tables (audit, audit_page) accessed through the repository pattern in src/server/features/audit/repositories/AuditRepository.ts.

Frequently Asked Questions

What is the page crawl limit when using OpenSEO MCP for site audits?

Free-tier subscriptions allow up to 50 pages per audit crawl, a limit enforced in src/server/features/audit/services/AuditService.ts via the PAYMENT_REQUIRED constant. Larger crawls require a paid plan, which removes this restriction and allows processing hundreds or thousands of pages depending on your subscription level.

How do I authenticate requests to the OpenSEO MCP server?

All requests must include an Authorization header with a Bearer token format: Authorization: Bearer <YOUR_API_TOKEN>. Generate this token in the OpenSEO web interface under Settings → API Keys. The MCP server validates this JWT token before executing any tool methods, including audit operations.

Can I run Lighthouse performance audits through the OpenSEO MCP?

Yes. Set the lighthouse parameter to true when calling run_site_audit. When enabled, the SiteAuditWorkflow.ts executes Lighthouse for each crawled page and stores the resulting scores in the audit_page table. Retrieve these metrics later via get_audit_pages, which includes fields like lighthouseScore alongside standard SEO metadata.

Where does OpenSEO store audit data and results?

All audit state persists in Cloudflare D1 (SQLite) through the repository abstraction defined in src/server/features/audit/repositories/AuditRepository.ts. The system uses two primary tables: audit stores job-level metadata and status, while audit_page contains individual page records with titles, descriptions, canonical URLs, and optional Lighthouse data. This architecture ensures low-latency reads and ACID compliance for audit operations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}