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

> Master OpenSEO MCP for technical site audits. This guide details launching audits, monitoring progress, and retrieving SEO data using its JSON-RPC interface. Optimize your site effectively.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: how-to-guide
- Published: 2026-09-05

---

**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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/server/workflows/SiteAuditWorkflow.ts) executes the actual crawl. This Cloudflare Workflow respects [`robots.txt`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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.

```bash
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)

```bash
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:**

```json
{
  "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.

```javascript
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.

```bash
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).

```bash
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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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.