How to Get Site Audit Issues Using OpenSEO's MCP Tools: Complete API Guide

Retrieve site audit issues by sending an authenticated GET request to the MCP endpoint /mcp/v1/sites/{site-id}/audit-issues, then enrich the raw database records using the getIssueDescriptor() helper defined in src/shared/audit-issues.ts.

OpenSEO's Managed Cloud Platform (MCP) exposes comprehensive site audit data through a standardized REST API. The backend crawler stores discovered issues in the audit_issues table, which you can query programmatically to build reports, trigger workflows, or populate dashboards.

Understanding the Audit Issues Data Architecture

The audit system separates raw occurrence data from issue type definitions to optimize storage and maintainability.

Database Schema and Storage

Crawled issues persist in the audit_issues table defined in src/db/audit.schema.ts. Each row represents a specific instance of an SEO issue found on a particular URL.

The table stores:

• id – Primary key of the record
• type – Foreign key referencing the issue type catalog (e.g., blocked-page, missing-title)
• url – The specific URL where the issue was detected
• severity – Classification as critical, warning, or info (mirroring the IssueSeverity type)
• details – Optional JSON object containing crawler-specific context like redirect chains or canonical URLs
• created_at / updated_at – Database timestamps

Issue Type Definitions

Human-readable metadata lives in src/shared/audit-issues.ts. This file exports the AUDIT_ISSUE_TYPES constant containing the complete catalog of issue definitions and the getIssueDescriptor(type) function for runtime lookup.

When you retrieve raw records from the API, the type field contains only the key (e.g., missing-description). You must call getIssueDescriptor() client-side to resolve this into a title, explanation, and remediation steps.

Calling the MCP API Endpoint

The primary interface for fetching audit data is a standard HTTP GET request handled by src/api/mcp/audit-issues.ts.

Request Format

GET https://api.open-seo.com/mcp/v1/sites/<site-id>/audit-issues
Authorization: Bearer <your-api-key>
Accept: application/json

Replace <site-id> with your site's UUID. The endpoint requires the same authentication mechanism used across all MCP tools—either a dashboard-generated API key or a valid session cookie.

Response Structure

The API returns a JSON array where each element contains:

• id – The database record identifier
• type – Issue classification key from AUDIT_ISSUE_TYPES
• url – Affected page URL
• severity – Risk level (critical, warning, or info)
• details – Optional crawler metadata
• created_at / updated_at – ISO 8601 timestamps

Enriching Raw Data with Issue Descriptors

Raw API responses lack human-readable explanations. To display meaningful reports, map each issue through the descriptor system.

The getIssueDescriptor(type) function in src/shared/audit-issues.ts accepts an issue type string and returns an object with:

• title – Human-readable issue name
• explanation – Description of why this matters for SEO
• howToFix – Actionable remediation steps
• severity – Normalized severity level

This separation allows the database to store lightweight records while keeping descriptive content in version-controlled TypeScript.

Practical Implementation Examples

JavaScript and TypeScript Integration

Use the following pattern to fetch and enrich audit data in browser or Node.js environments:

import { getIssueDescriptor } from './src/shared/audit-issues.js';

async function fetchAuditIssues(siteId, apiKey) {
  const resp = await fetch(
    `https://api.open-seo.com/mcp/v1/sites/${siteId}/audit-issues`,
    {
      headers: { 
        Authorization: `Bearer ${apiKey}`,
        Accept: 'application/json'
      },
    }
  );

  if (!resp.ok) throw new Error(`Failed to fetch audit issues: ${resp.status}`);
  const issues = await resp.json();

  // Enrich each issue with human-readable descriptions
  return issues.map(issue => ({
    ...issue,
    ...getIssueDescriptor(issue.type),
  }));
}

// Example usage
fetchAuditIssues('123e4567-e89b-12d3-a456-426614174000', 'my-api-key')
  .then(data => console.log(data))
  .catch(console.error);

Using the OpenSEO CLI

For shell scripting and automation, use the bundled CLI tool implemented in scripts/cli-utils.ts:

# Output formatted JSON for processing

npx open-seo mcp sites 123e4567-e89b-12d3-a456-426614174000 audit-issues --output json

# Generate a readable table in terminal

npx open-seo mcp sites 123e4567-e89b-12d3-a456-426614174000 audit-issues --output table

# Export to CSV for spreadsheet analysis

npx open-seo mcp sites 123e4567-e89b-12d3-a456-426614174000 audit-issues --output csv > audit-report.csv

The CLI performs the same underlying HTTP request to src/api/mcp/audit-issues.ts and handles authentication via stored credentials.

Summary

• Data Location: Audit issues store in the audit_issues table, with type definitions maintained in src/shared/audit-issues.ts.
• API Endpoint: Use GET /mcp/v1/sites/{site-id}/audit-issues with Bearer token authentication.
• Data Enrichment: Call getIssueDescriptor() client-side to translate type keys into human-readable titles and fixes.
• Automation: Use the npx open-seo CLI for command-line access and CSV export without writing custom code.
• Implementation: The endpoint handler resides in src/api/mcp/audit-issues.ts.

Frequently Asked Questions

What authentication method does the MCP endpoint require?

The endpoint requires Bearer token authentication using an API key generated from the OpenSEO dashboard, or a valid session cookie for browser-based requests. Include the token in the Authorization: Bearer <token> header.

Where are the human-readable issue descriptions stored?

Descriptions are not stored in the database. They live in src/shared/audit-issues.ts within the AUDIT_ISSUE_TYPES constant. The getIssueDescriptor() function retrieves these definitions at runtime, keeping the API payload small and allowing issue definitions to update without database migrations.

Can I export audit issues directly from the command line?

Yes. The OpenSEO CLI provides direct export capabilities. Run npx open-seo mcp sites <site-id> audit-issues --output csv to generate a CSV file, or use --output json for machine-readable format suitable for piping into other tools.

What severity levels are available in the audit data?

The severity field returns one of three values defined in the IssueSeverity type: critical for blocking errors, warning for optimization opportunities, and info for minor suggestions. These classifications help prioritize remediation efforts.

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