How to Integrate AI Agents with OpenSEO Using the MCP Server

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
2. Tool registration – Registers all SEO tools via registerOpenSeoMcpTools in 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).

Configuring the MCP Server Connection

Claude Code Setup

Add OpenSEO as an MCP server using the CLI:

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

This command is documented in 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 configuration file in your workspace:

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

Reference the Cursor-specific section in 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:

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.

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 (lines 44-60):

// 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:

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 (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 maintains state across related requests within a session.

Example workflow for content optimization:

// 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 demonstrates the expected response structure:

// 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 (lines 1-33, 44-90) – Core server bootstrap, McpServer creation, and dual-mode authentication handlers
• src/server/mcp/server.ts (lines 34-100) – Tool registration loop and instrumentation wiring
• src/server/mcp/tools/research-keywords.ts – Reference implementation for tool handlers with validation, backend calls, and response formatting
• src/server/mcp/context.ts – McpAuthContext definition for scope enforcement and credit tracking
• web/content/docs/mcp.md – End-user configuration guide for Claude, Cursor, and generic clients
• 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 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 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 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).

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