# What Is the Model Context Protocol (MCP) Server in OpenSEO?

> Explore OpenSEO's Model Context Protocol (MCP) server, an HTTP endpoint providing SEO tools like keyword research and SERP inspection to AI clients. Enhance your SEO workflow today.

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

---

**OpenSEO's Model Context Protocol (MCP) server is an HTTP endpoint at `/mcp` that exposes SEO-focused tools—keyword research, SERP inspection, backlink profiling, and more—to any MCP-compatible AI client such as Claude, Cursor, or Codex.**

The OpenSEO MCP server bridges AI agents and production SEO data. Instead of building custom integrations, developers and AI systems can invoke OpenSEO's backend services as remote procedures through a standardized protocol. This article explains how the MCP server works, how to authenticate and call it, and where the implementation lives in the every-app/open-seo repository.

## How the MCP Server Works

The MCP server operates as a layered HTTP pipeline. Each layer validates, authorizes, and routes requests to the correct SEO tool implementation.

### Transport Layer: Receiving MCP Requests

The [`src/server/mcp/transport.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.ts) file defines the entry point. It mounts on the path `/mcp` and performs three critical validations before handling any tool call:

- **CORS** validation for cross-origin browser requests
- **MCP headers** (`Mcp-Method`, `Mcp-Name`) identifying the requested tool
- **Authentication** via OAuth Bearer tokens or API keys

```bash
curl -X POST https://app.openseo.so/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Method: whoami" \
  -H "Mcp-Name: whoami" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -d '{}'

```

### Handler Dispatch and Context Building

Once validated, the transport creates an **MCP handler** using `createMcpHandler` from the `agents/mcp` package. This handler builds execution context through [`src/server/mcp/context.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/context.ts), which constructs a `ProjectMeta` object containing:

- The authenticated user ID
- The target project ID
- Granted scopes (`user`, `sam`, `mcp`)

This context enforces that AI clients receive **scoped access**—they cannot operate outside their authorized projects.

### Authorization and Tool Execution

Before any tool runs, two auth layers verify permissions:

- **[`src/server/mcp/project-auth.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/project-auth.ts)** – Ensures the caller owns or has access to the requested project
- **[`src/server/mcp/api-key-auth.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/api-key-auth.ts)** – Validates API key scope and rate limits

With authorization confirmed, the dispatcher routes to the appropriate tool in `src/server/mcp/tools/*`. Each tool implements specific SEO logic:

| Tool File | Purpose |
|-----------|---------|
| [`research-keywords.ts`](https://github.com/every-app/open-seo/blob/main/research-keywords.ts) | Keyword volume, difficulty, and opportunity metrics |
| [`get-serp-results.ts`](https://github.com/every-app/open-seo/blob/main/get-serp-results.ts) | Live search engine results page inspection |
| [`list-projects.ts`](https://github.com/every-app/open-seo/blob/main/list-projects.ts) | Enumerate available projects for the authenticated user |

Results are wrapped by `mcpResponse()` in [`src/server/mcp/formatters.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/formatters.ts) to ensure MCP-compatible JSON structure.

### Server Integration

The [`src/server/mcp/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/server.ts) file wires all components together and registers the endpoint as part of the main Fastify server defined in [`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts).

## Calling the OpenSEO MCP Server

### Using Claude's MCP CLI

Claude Code provides native MCP client support. Add OpenSEO as a remote server, then invoke tools directly:

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

claude mcp call openseo research-keywords '{"projectId":"proj_abc","keywords":["svelte","vite"]}'

```

The [`claude-code-plugin.md`](https://github.com/every-app/open-seo/blob/main/claude-code-plugin.md) documentation ([`web/content/docs/claude-code-plugin.md`](https://github.com/every-app/open-seo/blob/main/web/content/docs/claude-code-plugin.md)) contains detailed setup instructions for this integration.

### JavaScript/TypeScript Client

For programmatic access, use the `agents/mcp/client` package:

```javascript
import { createMcpClient } from "agents/mcp/client";

const client = createMcpClient({
  url: "https://app.openseo.so/mcp",
  headers: { Authorization: `Bearer ${process.env.OPENSEO_API_KEY}` },
});

async function research() {
  const res = await client.call({
    method: "research-keywords",
    name: "research-keywords",
    args: { projectId: "proj_1", keywords: ["react hooks"] },
  });
  console.log(res);
}

research();

```

The call routes through [`src/server/mcp/tools/research-keywords.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/research-keywords.ts), which queries the keyword-metrics database and returns structured rankings data.

## Implementing Custom MCP Tools

The modular architecture in `src/server/mcp/tools/` makes it straightforward to extend the server's capabilities. A new tool requires:

1. An async function accepting `ToolContext` and typed input
2. Return value wrapped by `mcpResponse()` for consistent formatting
3. Registration in [`src/server/mcp/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/server.ts)

```typescript
// src/server/mcp/tools/example-tool.ts
import { mcpResponse } from "@/server/mcp/formatters";
import { type ToolContext } from "@/server/mcp/context";

export async function exampleTool(ctx: ToolContext, input: { msg: string }) {
  return mcpResponse({
    result: { echo: input.msg, user: ctx.auth.userId },
    meta: { source: "mcp" },
  });
}

```

## Summary

- **OpenSEO's MCP server** exposes SEO tools through a standardized HTTP endpoint at `/mcp`, enabling AI agents to invoke keyword research, SERP analysis, and backlink profiling as remote functions.

- **Request flow**: Transport validation → context building → authorization → tool dispatch → formatted response.

- **Key source files**: [`src/server/mcp/transport.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.ts) (entry), [`src/server/mcp/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/server.ts) (orchestration), `src/server/mcp/tools/*` (implementations), [`src/server/mcp/formatters.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/formatters.ts) (response wrapping).

- **Authentication**: OAuth Bearer tokens or scoped API keys, enforced by [`project-auth.ts`](https://github.com/every-app/open-seo/blob/main/project-auth.ts) and [`api-key-auth.ts`](https://github.com/every-app/open-seo/blob/main/api-key-auth.ts).

- **Documentation**: [`web/content/docs/mcp.md`](https://github.com/every-app/open-seo/blob/main/web/content/docs/mcp.md) covers endpoint configuration and available tools.

## Frequently Asked Questions

### What AI clients support the OpenSEO MCP server?

Any client implementing the **Model Context Protocol** can connect. Verified compatible clients include **Claude Code**, **Cursor**, and **Codex**. The protocol standardizes tool discovery, invocation, and response formatting so clients interact with OpenSEO without custom integration code.

### How do I authenticate requests to the MCP endpoint?

Authentication uses **OAuth 2.0 Bearer tokens** or **API keys** passed in the `Authorization: Bearer <token>` header. The [`src/server/mcp/api-key-auth.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/api-key-auth.ts) module validates key scope and rate limits, while [`src/server/mcp/project-auth.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/project-auth.ts) verifies project-level permissions. Generate API keys from your OpenSEO project settings.

### What SEO tools are available through the MCP server?

Available tools include **keyword research** (volume, difficulty, CPC), **SERP inspection** (live results for any query), **domain overview** (authority, backlink counts), **backlink profiling** (referring domains, anchor text), **rank tracking** (position history), and **Google Search Console data** (impressions, clicks, queries). The full list is documented in [`web/content/docs/mcp.md`](https://github.com/every-app/open-seo/blob/main/web/content/docs/mcp.md) and discoverable via MCP's tool introspection.

### Can I self-host or extend the MCP server?

Yes. The entire implementation is open-source in the **every-app/open-seo** repository. Fork the repository, modify tool implementations in `src/server/mcp/tools/`, or add new routes in [`src/server/mcp/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/server.ts). The `agents/mcp` package handles protocol compliance, so custom tools automatically work with standard MCP clients.