# How the OpenSEO MCP Server Enables AI Agent Integration

> Discover how the OpenSEO MCP server facilitates AI agent integration. Access SEO backend services like keyword research and site audits via a JSON-RPC interface.

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

---

**The OpenSEO MCP server exposes the platform's SEO backend through the Model Context Protocol, allowing any AI client to call keyword research, SERP lookups, and site audits via a standard JSON-RPC interface at `/mcp`.**

OpenSEO is an open-source SEO platform that ships with a built-in **MCP (Model Context Protocol) server** for AI agent integration. By implementing the official `@modelcontextprotocol` SDK, the repository transforms its backend into a discoverable toolset that Claude, Cursor, Codex, and other MCP-compatible agents can invoke without custom API integration.

## How the MCP Server Processes Requests

The OpenSEO MCP server handles each request through a four-stage pipeline implemented across [`src/server/mcp/transport.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.ts) and related modules.

### 1. Per-Request Server Instantiation

To support concurrent clients without memory exhaustion, [`src/server/mcp/transport.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.ts) creates a fresh `McpServer` instance (~5 MiB) for every incoming request:

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

```

This isolation pattern prevents state leakage between AI agents.

### 2. Tool Registration

The `registerOpenSeoMcpTools(server)` function in [`src/server/mcp/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/server.ts) attaches the full SEO tool library. Each tool follows the MCP contract by returning a `mcpResponse` and lives in `src/server/mcp/tools/`:

- **Keyword research** ([`research-keywords.ts`](https://github.com/every-app/open-seo/blob/main/research-keywords.ts)) — volume, CPC, difficulty, related terms
- **SERP data** ([`search-console-tools.ts`](https://github.com/every-app/open-seo/blob/main/search-console-tools.ts)) — Google Search Console clicks, impressions, positions
- **Backlink inspection** ([`site-audit-tools.ts`](https://github.com/every-app/open-seo/blob/main/site-audit-tools.ts)) — counts, domain authority, anchor text
- **Saved keyword management** ([`save-keywords.ts`](https://github.com/every-app/open-seo/blob/main/save-keywords.ts), [`list-saved-keywords.ts`](https://github.com/every-app/open-seo/blob/main/list-saved-keywords.ts))

### 3. Handler Creation with Auth

The `createMcpHandler(server, { … })` from the `agents/mcp` package builds an HTTP handler that:

- Validates MCP-protocol headers
- Performs authentication/authorization via [`src/server/mcp/context.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/context.ts)
- Routes JSON-RPC calls to registered tools

### 4. Endpoint Exposure

The handler mounts to the Next.js API route in [`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts), making `https://app.openseo.so/mcp` the single entry point for all MCP clients.

## Authentication and Project Scoping

Every request must include an `Authorization` header. The context code 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 through `buildProjectMeta` and enforces the `mcp` scope.

The [`src/server/mcp/project-auth.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/project-auth.ts) helper wraps each tool to ensure agents can only access projects they own or collaborate on.

## Why MCP Works for AI Agents

MCP defines a **language-agnostic JSON-RPC protocol** that agents treat as native function calls. OpenSEO's implementation eliminates hard-coded HTTP integrations—agents discover and invoke tools dynamically.

**Available operations include:**

- `research-keywords` — fetch keyword metrics from [`research-keywords.ts`](https://github.com/every-app/open-seo/blob/main/research-keywords.ts)
- `search-console.query` — pull live GSC data via [`search-console-tools.ts`](https://github.com/every-app/open-seo/blob/main/search-console-tools.ts)
- `site-audit.backlinks` — inspect link profiles through [`site-audit-tools.ts`](https://github.com/every-app/open-seo/blob/main/site-audit-tools.ts)
- `keywords.save` / `keywords.list` — manage custom keyword lists

All tools share the same endpoint, enabling complex SEO workflows through natural language orchestration.

## Connecting an AI Client

Add the MCP server URL to any compatible client with OpenSEO authentication:

```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);

```

## Adding Custom MCP Tools

Extend the server by creating a tool function that receives the MCP context and returns `mcpResponse`:

```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 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…
}

```

Agents call custom tools identically: `await mcp.call("my-custom-tool", { … })`.

## Key Implementation Files

| Purpose | File Path |
|---------|-----------|
| Per-request server & HTTP handler | [`src/server/mcp/transport.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.ts) |
| Tool registration | [`src/server/mcp/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/server.ts) |
| Auth and project context | [`src/server/mcp/context.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/context.ts) |
| Keyword research tool | [`src/server/mcp/tools/research-keywords.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/research-keywords.ts) |
| Search Console tools | [`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 tools | [`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) |
| Response formatting | [`src/server/mcp/formatters.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/formatters.ts) |
| URL construction | [`src/server/mcp/public-origin.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/public-origin.ts) |
| Project authorization wrapper | [`src/server/mcp/project-auth.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/project-auth.ts) |

## Summary

- **OpenSEO MCP server** runs at `/mcp` using the official `@modelcontextprotocol` SDK
- **Per-request isolation** via fresh `McpServer` instances prevents memory exhaustion
- **Standardized tools** for keyword research, SERP data, backlinks, and keyword management
- **JWT-based auth** with project scoping through [`context.ts`](https://github.com/every-app/open-seo/blob/main/context.ts) and [`project-auth.ts`](https://github.com/every-app/open-seo/blob/main/project-auth.ts)
- **Extensible architecture** for adding custom SEO tools without protocol changes

## Frequently Asked Questions

### What is MCP in OpenSEO?

MCP (Model Context Protocol) is an open standard that OpenSEO implements to expose its SEO backend as callable tools. The protocol uses JSON-RPC over HTTP, allowing any compatible AI agent to discover and invoke OpenSEO operations without custom API code.

### How do I authenticate with the OpenSEO MCP server?

Pass a valid OpenSEO JWT in the `Authorization` header. The server validates tokens through [`src/server/mcp/context.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/context.ts) and enforces project-level access via [`src/server/mcp/project-auth.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/project-auth.ts). Clients typically obtain tokens through OpenSEO's OAuth login flow.

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

Yes. The MCP endpoint mounts to any Next.js deployment of the open-source repository. Update [`src/server/mcp/public-origin.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/public-origin.ts) to reflect your domain, and configure the `/mcp` route in [`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts) for your infrastructure.

### Which AI clients work with OpenSEO's MCP server?

Any MCP-compatible client works, including Claude Desktop, Cursor, GitHub Copilot (CodeX), and custom implementations using `@modelcontextprotocol` SDKs. The server uses standard tool discovery and JSON-RPC invocation patterns defined by the MCP specification.