# What Is the MCP Server in OpenSEO? Architecture, Security, and Usage Guide

> Discover the MCP server in OpenSEO a secure API bridge for AI agents interacting with SEO data like keyword research backlink data and rank tracking Learn about its architecture security and usage.

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

---

**The MCP server in OpenSEO is a stateless, secure API bridge that enables AI agents to interact with SEO data—including keyword research, Search Console queries, backlink data, and rank tracking—through a scoped, schema-validated interface.**

OpenSEO's **MCP (Machine-Controlled Process) server** is built to power AI-driven SEO workflows. It exposes the platform's core data services to external AI clients while enforcing strict authentication and validation rules. This guide explains how the MCP server works, where it's implemented, and how to use it.

## How the MCP Server Works

The MCP server follows a **stateless request-response model**. Each incoming request carries its own authentication and scope context, eliminating the need for server-side session storage.

### Entry Point and Routing

All MCP traffic flows through a dedicated endpoint defined by `MCP_ROUTE` in [`src/server/mcp/transport.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.ts). The transport layer handles:

- **CORS headers** (`MCP_CORS_HEADERS`) for cross-origin compatibility
- **Auth context validation** (`MCP_AUTH_CONTEXT_PROP`)
- **Scope enforcement** (`MCP_SCOPE`)

Requests lacking the required `MCP_SCOPE` are rejected with a 403 status code at this layer.

### OAuth Integration

The MCP server reuses OpenSEO's existing OAuth infrastructure. In [`src/server/mcp/oauth-provider.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/oauth-provider.ts), tokens are verified to ensure they contain the `MCP_SCOPE` claim. This design prevents privileged SEO data from being accessible through standard user tokens.

## MCP Tools and Capabilities

Tool implementations live in `src/server/mcp/tools/` and follow a uniform JSON-RPC-like interface. Each tool defines:

- An `inputSchema` for request validation
- An `outputSchema` for response validation
- A `handler` function implementing the business logic

Available tool categories include:

- **Search Console tools** — query performance data, filter by dimensions
- **Saved keywords** — retrieve and manage keyword lists
- **Rank tracking** — monitor SERP positions over time
- **Backlink analysis** — fetch link profile data

### Output Schema Validation

All tool responses are validated against definitions in [`src/server/mcp/output-schemas.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/output-schemas.ts). This guarantees that AI clients receive correctly typed data and that schema violations surface as structured RPC errors rather than partial or malformed payloads.

## Security Architecture

The MCP server implements defense-in-depth for AI-to-platform interactions:

| Layer | Implementation | Location |
|-------|---------------|----------|
| Transport | CORS + auth context extraction | [`src/server/mcp/transport.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.ts) |
| Authentication | OAuth token validation with scope check | [`src/server/mcp/oauth-provider.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/oauth-provider.ts) |
| Authorization | `MCP_SCOPE` mandatory enforcement | [`src/server/mcp/transport.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.ts) |
| Output Safety | Schema validation before response | [`src/server/mcp/output-schemas.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/output-schemas.ts) |

## Code Examples

### Calling the MCP Endpoint

```javascript
const MCP_ENDPOINT = `${process.env.NEXT_PUBLIC_BASE_URL}/mcp`;
const token = /* obtain OAuth token with MCP_SCOPE */;

fetch(MCP_ENDPOINT, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`,
    'Mcp-Method': 'search_console',
    'Mcp-Name': 'get_queries',
  },
  body: JSON.stringify({
    domain: 'example.com',
    startDate: '2024-01-01',
    endDate: '2024-01-31',
  }),
})
  .then(r => r.json())
  .then(console.log);

```

### Defining a New MCP Tool

```typescript
// src/server/mcp/tools/example-tool.ts
import { tool } from '@/server/mcp/tools';

export const exampleTool = tool({
  name: 'example_tool',
  description: 'Demo tool that echoes input',
  inputSchema: z.object({ message: z.string() }),
  outputSchema: z.object({ echoed: z.string() }),
  async handler({ message }) {
    return { echoed: `You said: ${message}` };
  },
});

```

Tools registered this way are automatically exposed through the MCP server without manual route configuration.

## Key Source Files

- [`src/server/mcp/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/server.ts) — Server registration and bootstrap
- [`src/server/mcp/transport.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.ts) — Request handling, CORS, auth validation
- [`src/server/mcp/oauth-provider.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/oauth-provider.ts) — OAuth scope integration
- `src/server/mcp/tools/` — Individual tool implementations
- [`src/server/mcp/output-schemas.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/output-schemas.ts) — Response validation schemas
- [`web/src/lib/feature-pages.ts`](https://github.com/every-app/open-seo/blob/main/web/src/lib/feature-pages.ts) — UI feature flags exposing MCP capabilities

## Product Integration

The MCP server powers AI-assisted features throughout OpenSEO. Feature flags in [`web/src/lib/feature-pages.ts`](https://github.com/every-app/open-seo/blob/main/web/src/lib/feature-pages.ts) reference "OpenSEO MCP" links, indicating that users interact with MCP-driven workflows through the standard interface. This enables use cases like "AI-powered keyword discovery" and "AI-driven backlink analysis" where an AI agent queries, analyzes, and acts on SEO data on behalf of the user.

## Summary

- The **MCP server** provides a stateless, authenticated API for AI agents to access OpenSEO data and services
- **Security** is enforced through OAuth tokens with mandatory `MCP_SCOPE` at the transport layer
- **Tools** are modular, schema-validated, and auto-registered from `src/server/mcp/tools/`
- **Validation** ensures type-safe responses via [`src/server/mcp/output-schemas.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/output-schemas.ts)
- **Integration** spans the full OpenSEO platform through feature-flagged UI components

## Frequently Asked Questions

### What does MCP stand for in OpenSEO?

**MCP stands for Machine-Controlled Process.** It describes the server's purpose: enabling machine agents (AI systems) to control SEO processes programmatically through a structured, secure interface.

### How is the MCP server different from OpenSEO's regular API?

The MCP server is **scoped specifically for AI agents** and uses a tool-based, JSON-RPC-like protocol rather than RESTful resources. It enforces the `MCP_SCOPE` OAuth requirement and validates all outputs against strict schemas—design choices optimized for automated, stateless interaction rather than human-driven browsing.

### Can I use the MCP server without OAuth?

No. According to the source in [`src/server/mcp/transport.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.ts) and [`src/server/mcp/oauth-provider.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/oauth-provider.ts), every MCP request must present a valid OAuth token containing `MCP_SCOPE`. Requests without this scope are rejected with HTTP 403 before reaching any tool handler.

### Where are MCP tools defined in the codebase?

MCP tools are implemented as individual files in `src/server/mcp/tools/` and registered through the `tool()` helper. Each tool exports its name, description, input/output Zod schemas, and handler function. The server auto-discovers and exposes these without manual route wiring.