How to Integrate OpenSEO With Other Tools: MCP and API Methods Explained

OpenSEO can be integrated with other tools via its JSON-RPC MCP endpoint at /mcp, conventional REST API routes, and DataForSEO connectors, allowing any HTTP-capable client to access SEO data programmatically.

OpenSEO, maintained in the every-app/open-seo repository, functions as a plug-and-play backend service that exposes its full functionality through standardized web protocols. The architecture deliberately separates the core SEO engine from the presentation layer, enabling developers to embed keyword research, rank tracking, and backlink analysis into external applications without managing the underlying data pipelines.

Integration Architecture Overview

OpenSEO provides four distinct integration points that cater to different use cases, from AI agent integration to third-party data service connections.

MCP Server Endpoint

The Multipurpose Control Protocol (MCP) server in /src/server/mcp/server.ts exposes a JSON-RPC-style HTTP endpoint at /mcp that provides the complete set of OpenSEO services. This endpoint handles keyword research, rank tracking, backlink data, and saved-keyword management through a unified interface.

Authentication operates via the openSeoAuth context defined in /src/server/mcp/context.ts, supporting both first-party sessions and OAuth tokens. The server also implements CORS headers, making it safe for browser-based clients. To call a tool, send a POST request with a JSON-RPC payload specifying the desired tool name—such as search_console or get_backlinks_profile—and include the Authorization header with your Bearer token.

REST-Style API

Beyond the MCP layer, OpenSEO exposes conventional REST endpoints through /src/server.ts. These routes mirror the MCP functionality using standard HTTP verbs: GET for retrieval, POST for creation, PUT for updates, and DELETE for removal operations.

This interface follows the same authentication scheme as the MCP endpoint, using the openSeoAuth property or Authorization headers. The REST API is ideal for integrations that prefer resource-oriented URL patterns over RPC-style method calls.

DataForSEO Connector

OpenSEO integrates with the third-party DataForSEO service through a thin wrapper layer. By supplying your DataForSEO API key in the .env file as DATAFORSEO_API_KEY, OpenSEO forwards calls to DataForSEO while automatically handling rate limits and pagination.

This connector allows OpenSEO to act as a proxy to DataForSEO's extensive dataset, or you can call DataForSEO directly while using OpenSEO for specific SEO workflow management. The configuration details are documented in /README.md.

Webhooks and Event Hooks

The MCP layer emits instrumentation events via PostHog for every tool invocation, as implemented in /src/server/mcp/instrumentation.ts. These events can be subscribed to or forwarded to external services like Slack or Zapier, enabling reactive workflows that trigger when SEO data updates or specific thresholds are met.

Integration Workflow

Integrating an external tool with OpenSEO follows a predictable pattern across all supported interfaces.

1. Authenticate: Obtain an MCP auth context through first-party session cookies or OAuth tokens.
2. Call a Tool: Send a POST request to /mcp with a JSON-RPC payload containing the method name and parameters, or use the corresponding REST endpoint.
3. Process the Response: Extract data from the structuredContent field for rich JSON data or textContent for plain-text consumption.
4. Chain Actions: Persist returned keywords to your database, feed data into analytics pipelines, or trigger downstream webhooks based on the results.

Code Examples for External Integration

The following examples demonstrate calling OpenSEO from external scripts assuming an instance running at https://my-openseo.example.com.

JavaScript (Node.js) Integration

This example retrieves keyword data using the search_console tool via the MCP endpoint:

const fetch = require('node-fetch');

async function getKeywordData(keyword) {
  const response = await fetch('https://my-openseo.example.com/mcp', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer YOUR_MCP_TOKEN`,
    },
    body: JSON.stringify({
      jsonrpc: '2.0',
      id: 1,
      method: 'search_console',
      params: { keyword },
    }),
  });

  const { result } = await response.json();
  console.log('SERP data:', result.structuredContent);
}

getKeywordData('open source seo');

Python Integration

This snippet fetches backlink profiles using the get_backlinks_profile method:

import requests
import json

MCP_URL = 'https://my-openseo.example.com/mcp'
TOKEN = 'YOUR_MCP_TOKEN'

payload = {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "get_backlinks_profile",
    "params": {"domain": "example.com"},
}

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {TOKEN}",
}

resp = requests.post(MCP_URL, headers=headers, data=json.dumps(payload))
data = resp.json()
print(json.dumps(data['result']['structuredContent'], indent=2))

Key Implementation Files

Understanding the source structure helps when debugging integrations or extending functionality:

• /src/server/mcp/server.ts: Core MCP HTTP handler that routes all tool calls and manages request validation.
• /src/server/mcp/context.ts: Defines the openSeoAuth authentication context used across both first-party and OAuth client integrations.
• /src/server/mcp/tools/*.ts: Individual tool implementations including keyword research and backlink profile fetchers.
• /src/server.ts: Exposes REST API endpoints that provide the same functionality as the MCP layer through conventional HTTP routes.
• /docs/SELF_HOSTING_DOCKER.md: Documentation for deploying local instances that external tools can target.

Summary

• OpenSEO exposes two primary integration interfaces: a JSON-RPC MCP endpoint at /mcp and a conventional REST API, both defined in the every-app/open-seo repository.
• Authentication uses the openSeoAuth scheme with Bearer tokens, supporting both first-party sessions and OAuth via /src/server/mcp/context.ts.
• Any HTTP-capable client can integrate, including Python scripts, Node.js applications, React dashboards, and AI agents like Claude Code or Hermes.
• DataForSEO integration allows OpenSEO to act as a managed proxy for third-party SEO data, handling rate limits automatically.
• Instrumentation events in /src/server/mcp/instrumentation.ts enable webhook-style reactive integrations with external notification systems.

Frequently Asked Questions

What authentication method does OpenSEO use for external integrations?

OpenSEO uses the openSeoAuth context object defined in /src/server/mcp/context.ts, which supports both first-party session authentication and OAuth tokens. External clients must include an Authorization header with a Bearer token or provide the auth context in the request payload to access protected endpoints.

Can OpenSEO integrate with AI agents and automation tools?

Yes, OpenSEO's MCP endpoint is specifically designed for AI agent integration. The JSON-RPC interface at /mcp is already compatible with agents such as Claude Code, OpenClaw, and Hermes, which can call SEO tools like search_console and get_backlinks_profile using standard HTTP POST requests with structured JSON payloads.

Is it possible to self-host OpenSEO for internal tool integration?

Yes, the repository includes Docker configuration documented in /docs/SELF_HOSTING_DOCKER.md that allows you to deploy OpenSEO on your own infrastructure. Self-hosting enables internal tools to make HTTP requests to your private instance while maintaining control over the DataForSEO API key and authentication secrets stored in your .env file.

How does OpenSEO handle external data sources like DataForSEO?

OpenSEO acts as a thin wrapper around DataForSEO's API when you provide a DATAFORSEO_API_KEY in your environment configuration. The integration automatically forwards requests, manages rate limiting, and handles pagination, allowing your external tools to consume DataForSEO data through OpenSEO's unified MCP or REST interfaces rather than managing the third-party connection directly.

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