# How to Integrate AI Agents with OpenSEO Using the MCP Server

> Integrate AI agents with OpenSEO using the MCP server. Access real-time SEO tools as native functions with zero custom code. Learn how now.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: how-to-guide
- Published: 2026-08-05

---

**OpenSEO exposes an MCP (Model Context Protocol) server that lets any MCP-compatible AI client call real-time SEO tools as native functions, with zero custom integration code required.**

Integrating AI agents with OpenSEO unlocks fully automated SEO workflows powered by live keyword research, SERP analysis, and Search Console data. The **MCP server** in the every-app/open-seo repository provides a standardized protocol layer that bridges any MCP-aware client—Claude Code, Claude Desktop, Cursor, Codex, or custom agents—directly to OpenSEO's backend services.

## What Is the OpenSEO MCP Server?

The MCP server is a lightweight HTTP endpoint built on the Model Context Protocol specification. It exposes every SEO tool as a callable function with typed input/output schemas, authentication, and credit metering already handled.

According to the OpenSEO source code, the server architecture follows five distinct stages:

1. **Server instantiation** – Creates an `McpServer` with metadata in [`src/server/mcp/transport.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.ts)
2. **Tool registration** – Registers all SEO tools via `registerOpenSeoMcpTools` in [`src/server/mcp/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/server.ts)
3. **Handler instrumentation** – Wraps each handler with `instrumentMcpToolHandler` for logging and schema validation
4. **Authentication handling** – Supports both OAuth (hosted) and Cloudflare Access JWT (self-hosted) flows
5. **Request execution** – Routes JSON-RPC payloads to the appropriate tool handler and returns structured responses

This design guarantees **zero-drift** between the MCP definition and actual implementation—the same TypeScript tool definitions power both external MCP clients and OpenSEO's built-in chat assistant ([`src/server/features/sam/samChatTools.ts`](https://github.com/every-app/open-seo/blob/main/src/server/features/sam/samChatTools.ts)).

## Configuring the MCP Server Connection

### Claude Code Setup

Add OpenSEO as an MCP server using the CLI:

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

```

This command is documented in [`web/content/docs/mcp.md`](https://github.com/every-app/open-seo/blob/main/web/content/docs/mcp.md) (lines 22-24). The `--scope user` flag makes the server available across all Claude Code sessions for your user profile.

### Cursor IDE Setup

Create or edit the [`.cursor/mcp.json`](https://github.com/every-app/open-seo/blob/main/.cursor/mcp.json) configuration file in your workspace:

```json
{
  "mcpServers": {
    "openseo": {
      "url": "https://app.openseo.so/mcp"
    }
  }
}

```

Reference the Cursor-specific section in [`web/content/docs/mcp.md`](https://github.com/every-app/open-seo/blob/main/web/content/docs/mcp.md) (lines 38-53) for additional IDE-specific options.

### Generic HTTP Client

Any client capable of sending JSON-RPC 2.0 requests can invoke tools directly:

```http
POST /mcp HTTP/1.1
Host: app.openseo.so
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "researchKeywords",
  "params": {
    "keywords": ["open source seo", "seo keywords tool"],
    "projectId": "123"
  },
  "id": 1
}

```

This request flows through `handleAuthenticatedOpenSeoMcpRequest` → `handleOpenSeoMcpRequest` → `researchKeywordsTool.handler` in [`src/server/mcp/tools/research-keywords.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/research-keywords.ts).

## Authentication Modes for MCP Integration

### Hosted OpenSEO (OAuth)

For the managed `https://app.openseo.so/mcp` endpoint, requests must include valid OAuth credentials with the `MCP_SCOPE`. The validation logic lives in `handleAuthenticatedOpenSeoMcpRequest` at [`src/server/mcp/transport.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.ts) (lines 44-60):

```typescript
// Simplified auth check from transport.ts
const authContext = await verifyMcpScope(request);
if (!authContext) {
  throw new McpError(401, "Invalid or missing MCP_SCOPE");
}

```

Credits and rate limits are enforced automatically based on the authenticated user's subscription tier.

### Self-Hosted Deployment

Self-hosted instances support two authentication patterns, implemented in `handleSelfHostedOpenSeoMcpRequest` (lines 62-90):

- **Cloudflare Access JWT**: Validate against your Cloudflare Access policies
- **Local admin context**: No-auth mode for isolated development environments

Example cURL with Cloudflare Access:

```bash
curl -X POST https://my-selfhosted.example.com/mcp \
  -H "Authorization: Bearer <CF-Access-Token>" \
  -d '{"jsonrpc":"2.0","method":"getSerpResults","params":{"keyword":"open seo","page":1},"id":1}'

```

## Available MCP Tools for AI Agents

The `registerOpenSeoMcpTools` function in [`src/server/mcp/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/server.ts) (lines 34-100) registers the complete SEO toolkit. Each tool follows a consistent pattern:

| Tool Category | Example Method | Data Source |
|-------------|--------------|-------------|
| Keyword Research | `researchKeywords` | DataForSEO + internal DB |
| SERP Analysis | `getSerpResults` | Live search scraping |
| Backlink Overview | `getBacklinkData` | DataForSEO APIs |
| Search Console | `getSearchConsoleMetrics` | Google Search Console API |
| Site Audit | `runTechnicalAudit` | Crawler + lighthouse |

Every tool handler is wrapped with `instrumentMcpToolHandler` to ensure failures are logged to PostHog and schema validation remains strict. This instrumentation enforces concrete input/output types required by the MCP SDK.

## Building Custom Tool Interactions

### Direct Tool Invocation Pattern

AI agents can construct multi-step workflows by chaining tool calls. The `McpHandler` created by `createMcpHandler` in [`src/server/mcp/transport.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.ts) maintains state across related requests within a session.

Example workflow for content optimization:

```json
// Step 1: Research competitor keywords
{
  "jsonrpc": "2.0",
  "method": "researchKeywords",
  "params": {
    "seed": "mcp server seo integration",
    "competitors": ["example.com", "rival.io"],
    "limit": 50
  },
  "id": 1
}

// Step 2: Analyze SERP for top opportunity
{
  "jsonrpc": "2.0",
  "method": "getSerpResults",
  "params": {
    "keyword": "ai agent seo automation",
    "location": "us",
    "device": "desktop"
  },
  "id": 2
}

```

### Handling Tool Responses

Tool responses follow a standardized envelope defined in the MCP specification. The `researchKeywordsTool.handler` in [`src/server/mcp/tools/research-keywords.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/research-keywords.ts) demonstrates the expected response structure:

```typescript
// From research-keywords.ts
return {
  content: [{
    type: "text",
    text: JSON.stringify({
      keywords: validatedResults,
      creditsConsumed: calculation.credits,
      sources: ["dataforseo", "internal-cache"]
    })
  }]
};

```

Agents should parse the `content[0].text` field and handle the `creditsConsumed` value to track usage against subscription limits.

## Key Implementation Files

Understanding the source layout accelerates debugging and custom integrations:

- **[`src/server/mcp/transport.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.ts)** (lines 1-33, 44-90) – Core server bootstrap, `McpServer` creation, and dual-mode authentication handlers
- **[`src/server/mcp/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/server.ts)** (lines 34-100) – Tool registration loop and instrumentation wiring
- **[`src/server/mcp/tools/research-keywords.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/research-keywords.ts)** – Reference implementation for tool handlers with validation, backend calls, and response formatting
- **[`src/server/mcp/context.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/context.ts)** – `McpAuthContext` definition for scope enforcement and credit tracking
- **[`web/content/docs/mcp.md`](https://github.com/every-app/open-seo/blob/main/web/content/docs/mcp.md)** – End-user configuration guide for Claude, Cursor, and generic clients
- **[`src/server/features/sam/samChatTools.ts`](https://github.com/every-app/open-seo/blob/main/src/server/features/sam/samChatTools.ts)** – Internal skill registration that mirrors the MCP tool set, ensuring parity between external and built-in agents

## Performance and Reliability Considerations

The MCP server implements several safeguards for production workloads:

- **Request timeouts**: All tool handlers enforce deadlines to prevent hanging agent sessions
- **Credit metering**: Every tool call deducts from the authenticated context's balance atomically
- **Schema validation**: Input payloads are validated against Zod schemas before handler execution
- **Observability**: PostHog integration via `instrumentMcpToolHandler` captures latency, errors, and usage patterns

For high-throughput scenarios, the self-hosted option with Cloudflare Access provides edge caching and DDoS protection while maintaining the same tool semantics.

## Summary

- **OpenSEO's MCP server** enables AI agent integration through a standardized, typed protocol without custom scaffolding
- **Two authentication paths** cover hosted (OAuth + `MCP_SCOPE`) and self-hosted (Cloudflare JWT or no-auth) deployments
- **Tool registration** happens centrally in [`src/server/mcp/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/server.ts) with strict schema enforcement and instrumentation
- **Client configuration** requires only a URL endpoint for Claude Code, Cursor, Codex, or any JSON-RPC 2.0 client
- **Zero-drift guarantee** ensures MCP tools and the built-in OpenSEO assistant share identical definitions and behavior

## Frequently Asked Questions

### What MCP clients are compatible with OpenSEO?

Any client implementing the Model Context Protocol specification works with OpenSEO. Verified configurations exist for **Claude Code**, **Claude Desktop**, **Cursor**, and **OpenAI Codex**. Generic HTTP clients can send JSON-RPC 2.0 requests directly to the `/mcp` endpoint. The protocol is transport-agnostic beyond the HTTP binding OpenSEO provides.

### How does authentication work for team deployments?

Hosted deployments use OAuth 2.0 with a dedicated `MCP_SCOPE`. Each team member authenticates individually, and the `McpAuthContext` in [`src/server/mcp/context.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/context.ts) enforces per-user credit limits. Self-hosted teams can configure **Cloudflare Access** for SSO integration or disable authentication entirely for isolated internal networks.

### Can I extend the MCP server with custom tools?

Yes. The registration pattern in [`src/server/mcp/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/server.ts) accepts additional tool definitions following the same `instrumentMcpToolHandler` wrapper pattern. Custom tools must export a Zod input schema, an output schema, and an async handler. Rebuild and redeploy to propagate changes to all connected agents.

### What happens when credit limits are exceeded?

The `handleOpenSeoMcpRequest` function checks the `McpAuthContext` balance before executing any tool handler. Insufficient credits trigger an MCP error response with code `-32002` and a descriptive message. Agents should handle this gracefully—either prompting for credit purchase (hosted) or logging for admin review (self-hosted).