What Is the MCP Server in OpenSEO and How Developers Can Use It

The MCP server in OpenSEO acts as a standardized bridge that allows AI agents like Claude, Cursor, and Codex to call the platform's SEO APIs as native tools via the Model Context Protocol.

OpenSEO's MCP (Model Context Protocol) server exposes the platform's keyword research, SERP results, and rank-tracking capabilities through a single HTTP endpoint. By implementing the MCP specification, the server enables any compatible AI client to interact with OpenSEO's data sources without requiring custom API wrappers or complex authentication flows.

What Is the MCP Server in OpenSEO?

The MCP server is a lightweight HTTP service that transforms OpenSEO's SEO-specific APIs into standardized tool calls. Located at https://app.openseo.so/mcp, this server authenticates requests using your OpenSEO API key and routes them to the appropriate backend services.

According to the OpenSEO source code, the server centralizes functionality that would otherwise require multiple API integrations. When an AI agent sends a request to the MCP endpoint, the server handles authentication, project authorization, and data formatting before returning structured JSON responses that follow the MCP specification.

Core Architecture and Implementation

The MCP server implementation spans several key files in the src/server/mcp/ directory:

• src/server/mcp/server.ts – The core implementation that registers available tools, parses incoming MCP requests, and orchestrates the response flow.
• src/server/mcp/transport.ts – Handles the HTTP transport layer that exposes the /mcp endpoint to external clients.
• src/server/mcp/context.ts – Provides request-scoped authentication context and project metadata for all tool executions.
• src/server/mcp/project-auth.ts – Enforces per-project access control, ensuring agents can only access authorized data.

Individual tools are modularized under src/server/mcp/tools/. For example, src/server/mcp/tools/search-keywords.ts implements keyword research functionality, while src/server/mcp/tools/get-serp-results.ts handles live SERP lookups.

How Developers Can Interact with the MCP Server

Developers can integrate with the OpenSEO MCP server through two primary methods: configuring an MCP client or making direct HTTP requests.

Configure an MCP Client

The simplest way to start using the MCP server in OpenSEO is to register the endpoint with your AI agent's configuration. The repository's documentation in web/content/docs/mcp.md provides specific CLI commands and JSON configurations for popular clients:

Claude (CLI configuration):

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

Codex (CLI configuration):

codex mcp add openseo --url https://app.openseo.so/mcp

Cursor (mcp.json configuration):

{
  "mcpServers": {
    "openseo": {
      "url": "https://app.openseo.so/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_OPENSEO_API_KEY"
      }
    }
  }
}

Once configured, the AI agent can invoke OpenSEO tools naturally during conversations, such as requesting keyword research or retrieving SERP data for specific domains.

Call MCP-Exposed Tools Directly

For custom applications or scripts, developers can send standard MCP requests directly to the endpoint. Each tool is exposed as a POST endpoint under the /mcp path.

Direct JavaScript fetch example:

const endpoint = 'https://app.openseo.so/mcp/search-keywords';
const apiKey = 'YOUR_OPENSEO_API_KEY';

const payload = {
  projectId: 'proj_12345',
  keywords: ['react hooks', 'typescript tutorial'],
  includeMetrics: true
};

fetch(endpoint, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${apiKey}`
  },
  body: JSON.stringify(payload)
})
  .then(res => res.json())
  .then(data => console.log('Keyword data:', data));

Using the built-in handler in Node.js:

import { createMcpHandler } from 'agents/mcp/server';
import { getMcpAuthContext } from '@/server/mcp/context';

// Initialize the handler (as used by the server under the /mcp route)
const handler = createMcpHandler({
  authContext: getMcpAuthContext(),
});

// Directly invoke the search-keywords tool
const result = await handler.invokeTool('search-keywords', {
  projectId: 'proj_12345',
  query: 'open source seo tools',
  includeMetrics: true
});

console.log(result);

Security and Project Authorization

The MCP server implements robust access controls through the src/server/mcp/project-auth.ts module. This ensures that AI agents can only access projects explicitly authorized by the API key owner.

When a request arrives, the server validates the Bearer token against OpenSEO's authentication service, then checks project-level permissions before executing any tool. This prevents unauthorized access to sensitive SEO data while maintaining the simplicity of a single endpoint configuration.

Summary

• The MCP server in OpenSEO provides a standardized interface at https://app.openseo.so/mcp for AI agents to consume SEO data.
• Core implementation files reside in src/server/mcp/, with tool definitions in src/server/mcp/tools/.
• Developers interact with the server by configuring MCP clients (Claude, Cursor, Codex) or sending direct HTTP POST requests.
• Built-in project authorization in src/server/mcp/project-auth.ts ensures secure, scoped access to data.
• The server eliminates the need for custom API wrappers by exposing OpenSEO functionality through the Model Context Protocol specification.

Frequently Asked Questions

What AI clients are compatible with the OpenSEO MCP server?

Any AI client that supports the Model Context Protocol can connect to OpenSEO's MCP server, including Claude Desktop, Cursor, and Codex CLI. The server follows the standard MCP HTTP transport specification, making it compatible with any MCP-compliant tool or agent.

Do I need a separate Google Cloud setup to use the Google Search Console features via MCP?

No. As documented in web/content/docs/google-search-console-mcp.mdx, the OpenSEO MCP server handles GSC authentication internally. You only need your OpenSEO API key; the server manages the underlying Google Cloud credentials and OAuth flows, allowing immediate access to GSC data through MCP tool calls without separate Google Cloud configuration.

How does the MCP server handle authentication and security?

The server validates all requests using Bearer token authentication passed in the Authorization header. Beyond API key validation, the src/server/mcp/context.ts module establishes a request-scoped authentication context, while src/server/mcp/project-auth.ts enforces that users can only access projects they own or have explicit permissions for, preventing cross-project data leakage.

Can I extend the MCP server with custom tools?

Yes. The modular architecture in src/server/mcp/tools/ allows developers to add new MCP tools by creating TypeScript files that export tool definitions following the established pattern. New tools must be registered in src/server/mcp/server.ts to become available through the MCP endpoint, maintaining consistency with the existing tool ecosystem.

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