# OpenSEO MCP Server and Audit System Documentation: A Complete Guide

> Find comprehensive OpenSEO MCP server and audit system documentation. Explore guides, tool schemas, and UI features for seamless integration and advanced auditing.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: documentation
- Published: 2026-08-21

---

**The OpenSEO MCP server documentation is located in [`web/content/docs/mcp.md`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/server.ts). The `createOpenSeoMcpServer` function (lines 31-44) instantiates the server with version metadata and branding:

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

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

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

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

```

The response contains real-time execution metrics:

```json
{
  "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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/server.ts) (construction and tool registration), [`transport.ts`](https://github.com/every-app/open-seo/blob/main/transport.ts) (HTTP/CORS handling), and [`oauth-registration.ts`](https://github.com/every-app/open-seo/blob/main/oauth-registration.ts) (authentication)
- **Site-audit MCP tools** are 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), exposing `run_site_audit`, `get_audit_status`, `get_audit_issues`, and `get_audit_pages`
- **Audit workflow orchestration** occurs in [`src/server/workflows/siteAuditWorkflowPhases.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/web/content/docs/mcp.md) within the every-app/open-seo repository, containing the "Set up OpenSEO MCP" guide. The [`README.md`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/site-audit-tools.ts), while [`src/server/features/audit/repositories/AuditRepository.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/oauth-registration.ts) (lines 49-57). The transport layer in [`src/server/mcp/transport.ts`](https://github.com/every-app/open-seo/blob/main/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.