OpenSEO MCP Server and Audit System Documentation: A Complete Guide

The OpenSEO MCP server documentation is located in web/content/docs/mcp.md and the README's "OpenSEO MCP & Agent Skills" section, while the site-audit system documentation is distributed across MCP tool schemas in src/server/mcp/tools/site-audit-tools.ts and the UI feature guides.

The every-app/open-seo repository exposes comprehensive SEO research capabilities through a Model-Context-Protocol (MCP) server and a multi-phase site-auditing workflow. Locating the correct documentation and understanding the underlying source architecture is essential for integrating AI agents and automating technical SEO analysis at scale.

Locating the Official MCP Server Documentation

OpenSEO maintains documentation across two primary locations: a dedicated setup guide for AI client configuration and high-level repository documentation.

Primary Documentation Files

The canonical MCP documentation resides in web/content/docs/mcp.md. This file contains the "Set up OpenSEO MCP" guide, which provides connection instructions for Claude, Cursor, Codex, and API-key-based clients to the JSON-RPC endpoint at https://app.openseo.so/mcp.

According to the source, this guide covers:

• Authentication requirements using OAuth scopes
• Client-specific configuration parameters
• Complete tool listings and their input schemas

README Quick Reference

The repository README.md includes a dedicated section titled OpenSEO MCP & Agent Skills. This section provides quick-start links to the detailed setup page and summarizes the server's core capabilities, including keyword research, SERP lookup, backlink analysis, and rank tracking integrations.

MCP Server Architecture and Implementation

Understanding the documentation structure requires familiarity with the server's three-layer architecture: construction, tool registration, and transport handling.

Server Construction

The MCP server entry point is src/server/mcp/server.ts. The createOpenSeoMcpServer function (lines 31-44) instantiates the server with version metadata and branding:

const server = new McpServer(
  {
    name: "OpenSEO MCP",
    title: "OpenSEO",
    version: "0.0.12",
    description: "...",
    websiteUrl: "https://openseo.so",
    icons: [{ src: "https://openseo.so/android-chrome-512x512.png", mimeType: "image/png", sizes: ["512x512"] }],
  },
  {
    instructions: "OpenSEO research tools use credits …",
  },
);

Tool Registration System

Each SEO tool is registered via registerOpenSeoTool (lines 99-125), which performs three critical operations:

• Normalizes input and output schemas using objectSchema
• Instruments handlers with instrumentMcpToolHandler for logging and performance timing
• Injects authentication and project context through createMcpToolContext

Transport Layer and Authentication

The HTTP transport implementation lives in src/server/mcp/transport.ts (lines 10-28). This layer:

• Exposes the /mcp endpoint with required CORS headers
• Validates the OAuth MCP_SCOPE scope (values: "user" or "project")
• Forwards validated requests to the McpServer instance

The OAuth registration logic is defined in src/server/mcp/oauth-registration.ts (lines 49-57), establishing the credential flow required for all MCP connections.

Site-Audit System Documentation and Source

The site-audit subsystem combines real-time MCP tooling with background workflow orchestration. Documentation for this system spans tool definitions, workflow logic, and data persistence layers.

MCP-Exposed Audit Tools

The public API for audits is defined in src/server/mcp/tools/site-audit-tools.ts, which exposes four JSON-RPC methods:

• run_site_audit: Initiates crawls, returning an auditId and dashboard URL
• get_audit_status: Provides real-time progress metrics including current phase and pages crawled
• get_audit_issues: Returns prioritized SEO issues in structured and CSV formats
• get_audit_pages: Retrieves raw page-level crawl results

The run_site_audit handler (lines 85-100) accepts projectId, url, maxPages, and runLighthouse parameters.

Workflow Orchestration

The audit execution engine is implemented in src/server/workflows/siteAuditWorkflowPhases.ts. The runAuditPhases function (lines 52-104) coordinates four sequential phases:

1. Discovery: Parses robots.txt and seeds the crawl frontier via discoverUrls
2. Crawl: Walks the site topology, recording each page through AuditRepository
3. Lighthouse: Optionally collects Core Web Vitals for sampled pages
4. Finalisation: Executes multipage checks, persists issues, and updates audit status

Transient progress tracking utilizes AuditProgressKV (lines 77-87), enabling the get_audit_status tool to report real-time metrics during long-running operations.

Data Persistence Layer

Audit data management is centralized in src/server/features/audit/repositories/AuditRepository.ts. This repository provides methods including:

• insertLighthouseResults: Stores performance metrics
• updateAuditProgress: Updates phase completion percentages
• insertIssues: Records detected technical SEO problems
• getPagesForAudit: Retrieves crawled page metadata and content hashes

Using the MCP Audit Endpoints

The documentation specifies exact JSON-RPC payloads for programmatic audit interaction.

Starting a Site Audit

Submit a POST request to https://app.openseo.so/mcp with the following JSON-RPC body:

{
  "jsonrpc": "2.0",
  "method": "run_site_audit",
  "params": {
    "projectId": "proj_ABC123",
    "url": "https://example.com",
    "maxPages": 200,
    "runLighthouse": true
  },
  "id": 1
}

The response includes the auditId and a direct link to the UI results page:

{
  "jsonrpc": "2.0",
  "result": {
    "auditId": "audit_XYZ789",
    "meta": {
      "projectId": "proj_ABC123",
      "url": "https://app.openseo.so/p/proj_ABC123/audit?auditId=audit_XYZ789"
    },
    "text": "Audit audit_XYZ789 started for https://example.com. ..."
  },
  "id": 1
}

Monitoring Audit Progress

Poll the audit state using get_audit_status:

{
  "jsonrpc": "2.0",
  "method": "get_audit_status",
  "params": {
    "projectId": "proj_ABC123",
    "auditId": "audit_XYZ789"
  },
  "id": 2
}

The response contains real-time execution metrics:

{
  "jsonrpc": "2.0",
  "result": {
    "status": {
      "id": "audit_XYZ789",
      "status": "running",
      "currentPhase": "crawling",
      "pagesCrawled": 42,
      "pagesTotal": 200,
      "lighthouseCompleted": 0,
      "lighthouseTotal": 0
    },
    "meta": { "projectId": "proj_ABC123", "url": "/p/proj_ABC123/audit?auditId=audit_XYZ789" },
    "text": "Audit audit_XYZ789 (https://example.com): running — phase crawling, 42/200 pages."
  },
  "id": 2
}

Retrieving Audit Issues

After workflow completion, fetch prioritized findings using get_audit_issues with identical parameters. The response returns both a human-readable text summary and a structuredContent array containing individual issue objects with severity ratings and remediation guidance.

Summary

• Primary MCP documentation resides in web/content/docs/mcp.md with quick-reference links in the README's OpenSEO MCP & Agent Skills section
• MCP server implementation is split across src/server/mcp/server.ts (construction and tool registration), transport.ts (HTTP/CORS handling), and oauth-registration.ts (authentication)
• Site-audit MCP tools are defined in src/server/mcp/tools/site-audit-tools.ts, exposing run_site_audit, get_audit_status, get_audit_issues, and get_audit_pages
• Audit workflow orchestration occurs in src/server/workflows/siteAuditWorkflowPhases.ts via runAuditPhases, managing discovery, crawling, Lighthouse analysis, and finalization
• Data persistence is handled by src/server/features/audit/repositories/AuditRepository.ts, with transient progress stored in AuditProgressKV for real-time status reporting

Frequently Asked Questions

Where is the OpenSEO MCP server documentation located?

The canonical documentation is found in web/content/docs/mcp.md within the every-app/open-seo repository, containing the "Set up OpenSEO MCP" guide. The README.md file also includes an OpenSEO MCP & Agent Skills section that provides quick-start links and capability summaries for connecting AI clients to the JSON-RPC endpoint.

Which source files control the site-audit workflow?

The audit workflow is orchestrated by runAuditPhases in src/server/workflows/siteAuditWorkflowPhases.ts (lines 52-104), which coordinates discovery, crawling, Lighthouse analysis, and finalization phases. The MCP-exposed interface is implemented in src/server/mcp/tools/site-audit-tools.ts, while src/server/features/audit/repositories/AuditRepository.ts manages all database persistence operations for crawl data and issues.

How do I authenticate with the OpenSEO MCP server?

Authentication requires OAuth 2.0 credentials with the MCP_SCOPE scope (accepting values "user" or "project"), as defined in src/server/mcp/oauth-registration.ts (lines 49-57). The transport layer in src/server/mcp/transport.ts validates these tokens against the OAuth provider before forwarding requests to the MCP server instance, ensuring secure access to SEO research tools.

Can I run a site audit programmatically via the MCP API?

Yes. Submit a JSON-RPC request to https://app.openseo.so/mcp using the run_site_audit method with parameters including projectId, url, maxPages, and runLighthouse. After initiation, use get_audit_status to poll the currentPhase, pagesCrawled, and completion metrics, then retrieve finalized results using get_audit_issues once the workflow reaches the completed state.

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