What Is the OpenSEO MCP Server and How Does It Enable AI Agent Integration?

The OpenSEO MCP server exposes the platform’s SEO toolkit through a standardized Model Context Protocol interface, allowing AI agents to authenticate with project-scoped tokens and execute tools like keyword research and site audits via remote procedure calls.

The OpenSEO MCP server transforms the platform’s backend SEO services into first-class AI agent capabilities. By implementing the Model Context Protocol (MCP), the server exposes keyword research, SERP inspection, and Google Search Console data through a unified remote-procedure-call interface available at https://app.openseo.so/mcp. This architecture enables any MCP-compatible agent to programmatically access live SEO data and save findings back to OpenSEO projects without custom integration code.

What Is the OpenSEO MCP Server?

The MCP server is a core component built on the agents/mcp/server framework that standardizes how external AI clients interact with OpenSEO’s data layer. It acts as a secure bridge between AI agents and the platform’s proprietary SEO tools.

Core Architecture and Protocol

In src/server/mcp/transport.ts, the server creates a request handler via createMcpHandler that routes incoming HTTP requests to the appropriate tool implementations. Each tool returns a structured mcpResponse that the client can render or process further. The core server logic resides in src/server/mcp/server.ts, which validates authentication tokens and injects project context into every tool call.

Authentication and Project Scoping

When an AI client connects to the MCP endpoint at https://app.openseo.so/mcp, it authenticates through the OpenSEO OAuth flow or via API key. The server issues a project-scoped token that enforces permissions at the project level. Every subsequent request includes this token, allowing the server to validate access and automatically inject the projectId into tool calls, ensuring data isolation between projects.

How the MCP Server Enables AI Agent Integration

The server turns OpenSEO’s data services into programmable AI capabilities by exposing them through the standardized MCP interface.

Standardized Tool Exposure

Rather than requiring custom API integrations, the server exposes SEO functionality as discrete MCP tools. For example, src/server/mcp/tools/research-keywords.ts implements the researchKeywords tool, while src/server/mcp/tools/search-console-tools.ts provides Google Search Console access. Each tool follows the MCP specification, accepting standardized parameters and returning structured data that AI agents can consume directly.

Supported AI Clients and Connection Methods

Any MCP-compatible agent can connect to OpenSEO, including Claude Code, Claude Desktop, Cursor, and Codex CLI. Clients connect to the HTTP endpoint and authenticate once, then maintain a session using the project-scoped token. This eliminates the need for agents to manage complex OAuth flows or API key rotation for individual tool calls.

Key Implementation Files and Code Structure

The MCP implementation spans several critical files that handle transport, authentication, and tool logic:

• src/server/mcp/transport.ts – Creates the MCP handler via createMcpHandler and routes HTTP requests to tool implementations.
• src/server/mcp/server.ts – Core logic that validates tokens, enforces project-level permissions, and injects projectId context into tool calls.
• src/server/mcp/tools/research-keywords.ts – Implements keyword research functionality accessible via the researchKeywords method.
• src/server/mcp/tools/search-console-tools.ts – Exposes Google Search Console data retrieval through the MCP interface.
• src/server/mcp/tools/site-audit-tools.ts – Provides site audit capabilities via methods like getSiteAudit.
• web/content/docs/mcp.md – User-facing documentation describing the protocol and available methods.
• web/content/docs/skills/setup.md – Setup guide for connecting AI agents and installing Agent Skills.

Practical Examples: Connecting and Calling MCP Tools

Below are concrete implementations for connecting AI clients and executing SEO workflows through the MCP server.

Connecting Claude Code to the MCP Server

Add the remote MCP server and authenticate using the CLI:

# Register the OpenSEO MCP endpoint

claude mcp add --transport http --scope user openseo https://app.openseo.so/mcp

# Authenticate and obtain project-scoped token

claude mcp login openseo

Executing Keyword Research via MCP

Once connected, AI agents can call the researchKeywords tool with project context:

// Retrieve keyword data through the MCP client
const keywords = await mcpClient.call('researchKeywords', {
  projectId: 'proj_123',
  query: 'best SEO tools',
  limit: 10
});

console.log(keywords);

Saving Data Back to OpenSEO Projects

Agents can persist findings directly to the OpenSEO project using the saveKeywords method:

// Save selected keywords to the project
await mcpClient.call('saveKeywords', {
  projectId: 'proj_123',
  keywords: ['seo tools', 'open source seo']
});

Available SEO Tools via MCP

The OpenSEO MCP server exposes the full platform capabilities through standardized methods:

• Keyword Research – Access search volumes, difficulty scores, and related terms via researchKeywords in src/server/mcp/tools/research-keywords.ts.
• SERP Inspection – Retrieve real-time search engine results page data for any query.
• Google Search Console Integration – Fetch performance metrics, indexing status, and query data through src/server/mcp/tools/search-console-tools.ts.
• Site Audit Capabilities – Execute technical SEO audits and retrieve crawl reports via methods in src/server/mcp/tools/site-audit-tools.ts.
• Backlink Analysis – Examine domain authority and link profiles.
• Rank Tracking – Monitor keyword position changes over time.

Summary

• The OpenSEO MCP server implements the Model Context Protocol to expose SEO tools through a standardized remote-procedure-call interface.
• Authentication uses project-scoped tokens issued via OAuth or API keys, ensuring secure, isolated access to project data.
• The server architecture centers on src/server/mcp/transport.ts for request routing and src/server/mcp/server.ts for token validation and context injection.
• AI agents connect to https://app.openseo.so/mcp and can execute tools like researchKeywords, access Google Search Console data, and save results without custom integration code.
• Tool implementations reside in src/server/mcp/tools/, with each file handling a specific SEO domain such as keyword research or site audits.

Frequently Asked Questions

What protocol does the OpenSEO MCP server use?

The server implements the Model Context Protocol (MCP), a standardized framework for exposing tools and data to AI agents. This protocol is handled by the agents/mcp/server framework, with transport managed in src/server/mcp/transport.ts via the createMcpHandler function.

How does authentication work with the OpenSEO MCP server?

Authentication occurs through the OpenSEO OAuth flow or API key exchange at the https://app.openseo.so/mcp endpoint. Upon successful authentication, the server issues a project-scoped token that must accompany every subsequent request. As implemented in src/server/mcp/server.ts, this token validates permissions and automatically injects the projectId into tool calls.

Which AI agents can connect to OpenSEO via MCP?

Any MCP-compatible client can connect, including Claude Code, Claude Desktop, Cursor, and Codex CLI. These clients use standard HTTP transport to reach the endpoint and maintain authenticated sessions using the project-scoped tokens provided by the OpenSEO authentication layer.

What SEO tasks can AI agents perform through the MCP server?

Agents can execute the full range of OpenSEO capabilities: keyword research via researchKeywords, site audits through getSiteAudit, Google Search Console data retrieval, backlink analysis, rank tracking, and SERP inspection. Agents can also write data back to projects using methods like saveKeywords, creating bidirectional workflows between AI reasoning and OpenSEO project storage.

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