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

> Access site audit issues via OpenSEO's MCP API. Learn how to make GET requests to retrieve and enrich audit data with this complete guide.

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

---

**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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/api/mcp/audit-issues.ts).

### Request Format

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

```javascript
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`](https://github.com/every-app/open-seo/blob/main/scripts/cli-utils.ts):

```bash

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