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

> Discover the MCP server in OpenSEO, a key component enabling AI agents like Claude and Codex to interact with SEO APIs as native tools using the Model Context Protocol. Learn how developers can leverage this integration.

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

---

**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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.ts)** – Handles the HTTP transport layer that exposes the `/mcp` endpoint to external clients.
- **[`src/server/mcp/context.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/context.ts)** – Provides request-scoped authentication context and project metadata for all tool executions.
- **[`src/server/mcp/project-auth.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/search-keywords.ts) implements keyword research functionality, while [`src/server/mcp/tools/get-serp-results.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/web/content/docs/mcp.md) provides specific CLI commands and JSON configurations for popular clients:

**Claude (CLI configuration):**

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

```

**Codex (CLI configuration):**

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

```

**Cursor (mcp.json configuration):**

```json
{
  "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:**

```javascript
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:**

```typescript
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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/context.ts) module establishes a request-scoped authentication context, while [`src/server/mcp/project-auth.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/server.ts) to become available through the MCP endpoint, maintaining consistency with the existing tool ecosystem.