# How the OpenSEO MCP Server Enables AI Agent Integration

> Integrate AI agents with OpenSEO's MCP server. Access SEO tools via JSON-RPC for real-time keyword research, SERP analysis, and backlink inspection. Seamless AI integration.

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

---

**OpenSEO's MCP server exposes the platform's SEO backend as a standardized set of JSON-RPC tools that any AI agent can invoke via the `/mcp` endpoint, enabling real-time keyword research, SERP analysis, and backlink inspection without hard-coded HTTP calls.**

The OpenSEO repository implements a Model Context Protocol (MCP) server that transforms its SEO backend into a language-agnostic interface for AI agents. By adhering to the official `@modelcontextprotocol` SDK, the platform allows compatible clients like Claude, Cursor, and Codex to execute complex SEO workflows through a single standardized endpoint.

## Architecture of the OpenSEO MCP Server

The MCP server follows a request-scoped architecture to ensure concurrent client connections remain memory-efficient and isolated.

### Request Lifecycle and Transport Layer

When a request hits the `/mcp` endpoint, [`src/server/mcp/transport.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.ts) instantiates a fresh `McpServer` instance for that specific connection. This per-request instantiation (approximately 5 MiB per instance) prevents memory exhaustion when handling multiple concurrent AI agents.

```typescript
const server = new McpServer({ /* …options… */ });

```

The transport layer then invokes `createMcpHandler(server, { … })` from the `agents/mcp` package to construct an HTTP handler. This handler validates MCP-protocol headers, manages authentication via [`src/server/mcp/context.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/context.ts), and routes JSON-RPC style calls to the appropriate registered tools.

### Tool Registration and Discovery

The function `registerOpenSeoMcpTools(server)`, defined in [`src/server/mcp/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/server.ts), populates the server instance with SEO-specific capabilities. Each tool resides in `src/server/mcp/tools/` and conforms to the MCP contract by returning a standardized `mcpResponse` object.

The registration process maps tool names to their implementations:

- **Keyword research** via [`research-keywords.ts`](https://github.com/every-app/open-seo/blob/main/research-keywords.ts)
- **Search Console queries** via [`search-console-tools.ts`](https://github.com/every-app/open-seo/blob/main/search-console-tools.ts)
- **Site audit utilities** via [`site-audit-tools.ts`](https://github.com/every-app/open-seo/blob/main/site-audit-tools.ts)
- **Saved keyword management** via [`save-keywords.ts`](https://github.com/every-app/open-seo/blob/main/save-keywords.ts) and [`list-saved-keywords.ts`](https://github.com/every-app/open-seo/blob/main/list-saved-keywords.ts)

### Authentication and Project Scoping

Every MCP request must include an `Authorization` header. The `buildProjectMeta` function in [`src/server/mcp/context.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/context.ts) extracts the user and project ID, enforcing the `mcp` scope before execution. Additionally, [`src/server/mcp/project-auth.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/project-auth.ts) wraps each tool invocation to ensure agents can only access OpenSEO projects explicitly granted to their authentication token.

## Core SEO Tools Available to AI Agents

The MCP server exposes the following SEO capabilities through standardized tool calls:

- **Keyword Research** ([`src/server/mcp/tools/research-keywords.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/research-keywords.ts)): Retrieves search volume, CPC, keyword difficulty, and related terms for any query.
- **SERP Analysis** ([`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)): Pulls live Google Search Console data including clicks, impressions, and average positions.
- **Backlink Inspection** ([`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)): Returns backlink counts, domain authority metrics, and anchor-text distributions.
- **Keyword Management** ([`src/server/mcp/tools/save-keywords.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/save-keywords.ts)): Persists and retrieves custom keyword lists associated with specific projects.

All tools return formatted responses via helpers in [`src/server/mcp/formatters.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/formatters.ts), ensuring consistent JSON structures that AI agents can parse reliably.

## Implementing AI Agent Connections

### Connecting from Claude, Cursor, or Codex

AI clients connect to OpenSEO by configuring the MCP endpoint URL and implementing the platform's JWT authentication flow. The following pseudocode demonstrates the connection pattern:

```typescript
// Pseudocode for any MCP-compatible client
const mcp = new McpClient({
  endpoint: "https://app.openseo.so/mcp",
  tokenProvider: async () => {
    // OpenSEO will pop a login window; return the issued JWT
    return await getOpenSeoJwt();
  },
});

// Example: ask the agent to research keywords for "budget travel"
const result = await mcp.call("research-keywords", {
  query: "budget travel",
  projectId: "proj_123",
});
console.log(result);

```

### Creating Custom MCP Tools

Developers can extend the OpenSEO MCP server by adding new tools that follow the established contract. A custom tool receives the MCP context and input parameters, then returns a formatted response:

```typescript
// src/server/mcp/tools/my-custom-tool.ts
import { mcpResponse } from "@/server/mcp/formatters";

export async function myCustomTool(ctx, input) {
  const data = await doSomethingSpecial(input);
  return mcpResponse({ data });
}

```

Register the new tool in [`src/server/mcp/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/server.ts):

```typescript
import { myCustomTool } from "./tools/my-custom-tool";

export function registerOpenSeoMcpTools(server) {
  server.registerTool("my-custom-tool", myCustomTool);
  // …other tools…
}

```

Once registered, AI agents can invoke the custom tool using the same `mcp.call()` pattern as native OpenSEO tools.

## Summary

- The OpenSEO MCP server converts SEO backend operations into standardized JSON-RPC tools accessible via the `/mcp` endpoint.
- [`src/server/mcp/transport.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.ts) creates isolated `McpServer` instances per request (~5 MiB each) to support high concurrency.
- Tool registration occurs in [`src/server/mcp/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/server.ts), while [`src/server/mcp/context.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/context.ts) and [`src/server/mcp/project-auth.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/project-auth.ts) handle authentication and project-level access control.
- AI agents can execute keyword research, SERP lookups, backlink analysis, and saved keyword management through a unified protocol without platform-specific HTTP integrations.
- Custom tools follow a simple contract—receiving context and input, returning `mcpResponse`—and integrate seamlessly into the existing tool registry.

## Frequently Asked Questions

### What is the Model Context Protocol (MCP) and why does OpenSEO use it?

The Model Context Protocol is a language-agnostic JSON-RPC standard that allows AI agents to discover and invoke external tools as if they were local functions. OpenSEO implements MCP to eliminate the need for agents to hard-code HTTP client logic, instead providing a standardized interface that works across Claude, Cursor, Codex, and other compatible clients.

### How does OpenSEO handle authentication for MCP requests?

Every MCP request must include an `Authorization` header containing a valid JWT. The `buildProjectMeta` function in [`src/server/mcp/context.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/context.ts) validates this token and extracts the user and project ID, while [`src/server/mcp/project-auth.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/project-auth.ts) ensures the requesting agent has explicit access to the targeted OpenSEO project before executing any tool.

### Can I self-host the OpenSEO MCP server?

Yes. The MCP endpoint attaches to the standard Next.js API route defined in [`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts), meaning self-hosted instances can expose their own MCP URL (typically `https://your-domain.com/mcp`) by configuring the appropriate environment variables and authentication providers in [`src/server/mcp/context.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/context.ts).

### What is the memory overhead of concurrent MCP connections?

According to the source code in [`src/server/mcp/transport.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.ts), each MCP request instantiates a fresh `McpServer` instance consuming approximately 5 MiB of memory. This per-request isolation prevents resource exhaustion when multiple AI agents connect simultaneously, though system administrators should capacity-plan based on expected concurrent connection volumes.