# OpenSEO MCP Tools and Agent Skills: Complete API Reference

> Discover OpenSEO MCP tools and agent skills available in the every-app/open-seo repository. Access 30+ MCP tools for SEO data and 16 agent skills for automation via the /mcp endpoint.

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

---

**OpenSEO exposes 30+ Model Context Protocol (MCP) tools for SEO data retrieval and 16 agent skills for workflow automation, all accessible via the `/mcp` endpoint in the `every-app/open-seo` repository.**

OpenSEO is an open-source SEO platform that implements the **Model Context Protocol (MCP)** to expose server-side utilities to AI agents. The codebase at `every-app/open-seo` contains a comprehensive suite of **MCP tools** for technical SEO audits, keyword research, and rank tracking, alongside **agent skills** that orchestrate these tools into actionable workflows.

## MCP Tools Available in OpenSEO

All MCP tools reside in `src/server/mcp/tools/` and follow a consistent structure: each exports an object containing a `name`, `config` (with title and description), and Zod-validated input/output schemas. The server registers these automatically via [`src/server/mcp/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/server.ts) and exposes them through the single JSON-RPC endpoint at `/mcp`.

### Identity and Session Management

The `whoami` tool ([`src/server/mcp/tools/whoami.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/whoami.ts)) returns the current MCP client identity and session context. This is typically the first call an agent makes to verify connectivity and retrieve project metadata before executing other operations.

### 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), these utilities trigger Lighthouse-style technical audits:

- **`run_site_audit`** – Initiates a new crawl and performance analysis
- **`get_audit_status`** – Polls for completion status of a running audit
- **`get_audit_issues`** – Retrieves structured issue lists (performance, accessibility, SEO)
- **`get_audit_pages`** – Lists all URLs discovered during the crawl

### Search Console Integration

Tools in [`src/server/mcp/tools/search-console-tools.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/search-console-tools.ts) bridge Google Search Console data:

- **`get_search_console_performance`** – Pulls organic impressions, clicks, and CTR data
- **`inspect_urls`** – Returns GSC inspection results for specific URL sets

### Keyword Management

The keyword suite spans multiple files for research and storage:

- **`research_keywords`** ([`research-keywords.ts`](https://github.com/every-app/open-seo/blob/main/research-keywords.ts)) – Executes DataForSEO research jobs and returns raw volume/competition data
- **`save_keywords`** ([`save-keywords.ts`](https://github.com/every-app/open-seo/blob/main/save-keywords.ts)) – Persists keyword lists to the project's database
- **`list_saved_keywords`** ([`list-saved-keywords.ts`](https://github.com/every-app/open-seo/blob/main/list-saved-keywords.ts)) – Retrieves previously stored keyword sets

### Project and Rank Tracker Management

Project lifecycle tools in `src/server/mcp/tools/` include:

- **`list_projects`** – Enumerates accessible projects
- **`create_project`** – Initializes new SEO projects
- **`create_rank_tracker`** – Configures position tracking for domain/keyword combinations
- **`get_rank_tracker`** – Fetches tracker configuration and status
- **`run_rank_tracker`** – Executes a ranking check across configured search engines
- **`add_rank_tracking_keywords`** and **`remove_rank_tracking_keywords`** – Modify tracker keyword sets
- **`estimate_rank_tracker_cost`** – Calculates credit consumption before execution

### Domain and Keyword Discovery

DataForSEO-backed research tools in [`src/server/mcp/tools/dataforseo-research-tools.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/dataforseo-research-tools.ts) and related files:

- **`get_domain_overview`** ([`get-domain-overview.ts`](https://github.com/every-app/open-seo/blob/main/get-domain-overview.ts)) – High-level traffic estimates and backlink counts
- **`get_domain_keyword_suggestions`** – Seed keyword generation from domain input
- **`get_ranked_keywords`** – Exact keyword list a domain currently ranks for
- **`get_backlinks_profile`** ([`get-backlinks-profile.ts`](https://github.com/every-app/open-seo/blob/main/get-backlinks-profile.ts)) – Granular backlink object lists
- **`get_backlinks_overview`** ([`get-backlinks-overview.ts`](https://github.com/every-app/open-seo/blob/main/get-backlinks-overview.ts)) – Aggregated referring domain metrics

### Google Analytics Tools

The [`src/server/mcp/tools/google-analytics-tools.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/google-analytics-tools.ts) file exposes GA4-derived SEO signals:

- **`get_google_analytics_organic_landing_pages`**
- **`get_google_analytics_page_performance`**
- **`get_google_analytics_key_events`**
- **`get_google_analytics_traffic_acquisition`**
- **`get_google_analytics_search_opportunities`**

These return structured JSON with session counts, conversion rates, and page-level engagement metrics.

### SERP and Local SEO Tools

SERP scraping and local business data reside in [`src/server/mcp/tools/get-serp-results.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/get-serp-results.ts) and [`src/server/mcp/tools/local-seo-tools.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/local-seo-tools.ts):

- **`get_serp_results`** – Raw SERP JSON including features, ads, and organic results
- **`search_local_businesses`** – DataForSEO local business listings
- **`get_local_serp_results`** – Maps and Places rankings for geographic queries
- **`get_google_business_questions`** – "People also ask" extraction for entities
- **`find_serp_competitors`** – Competitor domain identification for keywords
- **`get_keyword_metrics`** – Volume, CPC, keyword difficulty, and intent classification
- **`get_business_profile`**, **`get_business_reviews`**, **`get_local_rank_grid`** – Google Business Profile audits and local ranking visualization

## Agent Skills in OpenSEO

Agent skills are high-level workflow definitions stored in `.agents/skills/*/SKILL.md` files. The OpenAI-compatible agent runner consumes these markdown descriptors to orchestrate MCP tool calls into coherent SEO strategies.

### Core SEO Workflows

- **`seo-coach`** ([`seo-coach/SKILL.md`](https://github.com/every-app/open-seo/blob/main/seo-coach/SKILL.md)) – Conversational guidance that recommends tool sequences based on project maturity
- **`seo-audit`** – One-page technical audit execution and report generation
- **`seo-project-setup`** – Initial configuration covering MCP verification and Search Console linking
- **`keyword-research`** – End-to-end seed-to-opportunity workflows using `research_keywords`
- **`keyword-clustering`** – Intent-based grouping and content mapping logic
- **`competitive-landscape`** – Market winner identification and content pattern analysis
- **`competitor-analysis`** – Deep-dive single competitor profiling (keywords, backlinks, content gaps)
- **`local-seo`** – Google Business Profile audits and local rank tracking setup

### Development and Utility Skills

- **`link-prospecting`** – Link-building opportunity discovery and outreach drafting
- **`webapp-testing`** – UI automation helpers for end-to-end testing
- **`verify-local-mcp`** – Validates self-hosted MCP auth and CORS configurations
- **`simple-issue-description`** – Generates structured bug/feature tickets
- **`maintain-greptile-rules`** – Repository linting rule maintenance
- **`openseo-release-notes`** – Changelog formatting automation

## Using OpenSEO MCP Tools

### Calling Tools via JSON-RPC

The MCP endpoint at `/mcp` accepts JSON-RPC 2.0 payloads. The transport layer ([`src/server/mcp/transport.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.ts)) handles CORS, session validation via `mcp-session-id` headers, and request routing.

```javascript
const BASE = "https://app.open-seo.com";

async function getDomainOverview(projectId, domain) {
  const payload = {
    jsonrpc: "2.0",
    id: 1,
    method: "get_domain_overview",
    params: { projectId, domain },
  };

  const resp = await fetch(`${BASE}/mcp`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "mcp-session-id": "<your-session-id>",
    },
    body: JSON.stringify(payload),
  });

  const { result } = await resp.json();
  return result; // Contains structuredContent and text fields
}

```

The `get_domain_overview` tool definition in [`src/server/mcp/tools/get-domain-overview.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/get-domain-overview.ts) validates inputs using Zod schemas and returns standardized response objects via `mcpResponse` formatters.

### Registering New Tools

To extend the API, create a TypeScript file in `src/server/mcp/tools/` following the pattern from existing tools:

```typescript
import { z } from "zod";
import { mcpResponse } from "@/server/mcp/formatters";

export const myTool = {
  name: "my_tool",
  config: {
    title: "My Custom Tool",
    description: "Performs custom SEO analysis.",
    inputSchema: z.object({
      projectId: z.string(),
      targetUrl: z.string().url(),
    }),
    outputSchema: z.object({
      score: z.number(),
    }),
  },
  handler: async (args, context) => {
    // Context contains projectId, user permissions, billing quota
    const score = await analyzeUrl(args.targetUrl);
    return mcpResponse({ text: `Score: ${score}`, structuredContent: { score } });
  },
};

```

The server automatically imports all `*Tool` exports and registers them in the JSON-RPC router ([`src/server/mcp/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/server.ts)).

## Architecture Overview

The MCP implementation relies on three core components:

1. **Transport Layer** ([`src/server/mcp/transport.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.ts)) – HTTP entry point managing CORS headers, OAuth token validation (via [`src/server/mcp/oauth-provider.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/oauth-provider.ts)), and session persistence
2. **Context Builder** ([`src/server/mcp/context.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/context.ts)) – Constructs per-request metadata including project ID, billing limits, and user permissions passed to every tool handler
3. **Agent Runner** – Reads `.agents/skills/**/SKILL.md` files and `.agents/skills/**/agents/*.yaml` configurations to drive OpenAI agents that invoke MCP tools through the `/mcp` endpoint

This separation ensures **MCP tools provide raw data primitives** while **agent skills orchestrate those primitives into business workflows**.

## Summary

- OpenSEO contains **30+ MCP tools** across categories including site audits, Search Console, GA4, keyword research, rank tracking, and local SEO
- All tools are TypeScript implementations in `src/server/mcp/tools/` with Zod schema validation
- The **MCP endpoint** at `/mcp` uses JSON-RPC 2.0 and requires session authentication via `mcp-session-id` headers
- **16 agent skills** in `.agents/skills/` define high-level SEO workflows as markdown descriptors consumed by AI agents
- The architecture separates data access (MCP tools) from workflow logic (agent skills), enabling both programmatic API usage and AI-driven automation

## Frequently Asked Questions

### What is the Model Context Protocol (MCP) in OpenSEO?

The Model Context Protocol is a JSON-RPC-based interface that exposes OpenSEO's SEO data capabilities to AI agents. As implemented in `every-app/open-seo`, MCP provides a standardized way for agents to discover and invoke tools like `run_site_audit` or `get_search_console_performance` through a single HTTP endpoint (`/mcp`), reducing the integration surface for AI-driven SEO workflows.

### How do I authenticate requests to OpenSEO MCP tools?

Authentication uses OAuth 2.0 flows implemented in [`src/server/mcp/oauth-provider.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/oauth-provider.ts). Clients must obtain a session token and include it in the `mcp-session-id` header when posting JSON-RPC requests to `/mcp`. The transport layer validates these tokens against project permissions and billing quotas defined in [`src/server/mcp/context.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/context.ts).

### What is the difference between an MCP tool and an agent skill?

**MCP tools** are atomic functions (e.g., `research_keywords`, `get_backlinks_profile`) that perform single data-retrieval or action operations. **Agent skills** are high-level workflows defined in `.agents/skills/*/SKILL.md` files that describe how to sequence multiple MCP tools to achieve business outcomes like "perform a competitor analysis" or "set up rank tracking."

### Can I add custom MCP tools to my OpenSEO instance?

Yes. Create a new TypeScript file in `src/server/mcp/tools/` exporting a tool object with `name`, `config` (including Zod schemas), and a `handler` function. The server ([`src/server/mcp/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/server.ts)) auto-discovers these exports at runtime. Custom tools have access to the same context object (project ID, user permissions) as built-in tools.