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

> Discover the OpenSEO MCP server, an interface enabling AI agents to access SEO tools like keyword research and site audits using remote procedure calls and project-scoped tokens.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: deep-dive
- Published: 2026-09-02

---

**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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/research-keywords.ts) implements the `researchKeywords` tool, while [`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) 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`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.ts)** – Creates the MCP handler via `createMcpHandler` and routes HTTP requests to tool implementations.
- **[`src/server/mcp/server.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/research-keywords.ts)** – Implements keyword research functionality accessible via the `researchKeywords` method.
- **[`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)** – Exposes Google Search Console data retrieval through the MCP interface.
- **[`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)** – Provides site audit capabilities via methods like `getSiteAudit`.
- **[`web/content/docs/mcp.md`](https://github.com/every-app/open-seo/blob/main/web/content/docs/mcp.md)** – User-facing documentation describing the protocol and available methods.
- **[`web/content/docs/skills/setup.md`](https://github.com/every-app/open-seo/blob/main/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:

```bash

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

```javascript
// 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:

```javascript
// 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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.ts) for request routing and [`src/server/mcp/server.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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.