OpenSEO MCP Tools and Agent Skills: Complete API Reference

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 and exposes them through the single JSON-RPC endpoint at /mcp.

Identity and Session Management

The whoami tool (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, 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 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) – Executes DataForSEO research jobs and returns raw volume/competition data
• save_keywords (save-keywords.ts) – Persists keyword lists to the project's database
• list_saved_keywords (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 and related files:

• get_domain_overview (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) – Granular backlink object lists
• get_backlinks_overview (get-backlinks-overview.ts) – Aggregated referring domain metrics

Google Analytics Tools

The 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 and 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) – 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) handles CORS, session validation via mcp-session-id headers, and request routing.

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 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:

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).

Architecture Overview

The MCP implementation relies on three core components:

1. Transport Layer (src/server/mcp/transport.ts) – HTTP entry point managing CORS headers, OAuth token validation (via src/server/mcp/oauth-provider.ts), and session persistence
2. Context Builder (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. 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.

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) auto-discovers these exports at runtime. Custom tools have access to the same context object (project ID, user permissions) as built-in tools.

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