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

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. 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, 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. 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
Authentication	OAuth token validation with scope check	src/server/mcp/oauth-provider.ts
Authorization	MCP_SCOPE mandatory enforcement	src/server/mcp/transport.ts
Output Safety	Schema validation before response	src/server/mcp/output-schemas.ts

Code Examples

Calling the MCP Endpoint

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

// 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 — Server registration and bootstrap
• src/server/mcp/transport.ts — Request handling, CORS, auth validation
• src/server/mcp/oauth-provider.ts — OAuth scope integration
• src/server/mcp/tools/ — Individual tool implementations
• src/server/mcp/output-schemas.ts — Response validation schemas
• 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 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
• 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 and 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}