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

> Integrate OpenSEO with other tools using MCP, REST API, and DataForSEO connectors. Access SEO data programmatically from any HTTP client. Learn how to connect OpenSEO now.

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

---

**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`](https://github.com/every-app/open-seo/blob/main//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`](https://github.com/every-app/open-seo/blob/main//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`](https://github.com/every-app/open-seo/blob/main//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`](https://github.com/every-app/open-seo/blob/main//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`](https://github.com/every-app/open-seo/blob/main//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:

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

```python
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`](https://github.com/every-app/open-seo/blob/main//src/server/mcp/server.ts)**: Core MCP HTTP handler that routes all tool calls and manages request validation.
- **[`/src/server/mcp/context.ts`](https://github.com/every-app/open-seo/blob/main//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`](https://github.com/every-app/open-seo/blob/main//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`](https://github.com/every-app/open-seo/blob/main//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`](https://github.com/every-app/open-seo/blob/main//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`](https://github.com/every-app/open-seo/blob/main//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`](https://github.com/every-app/open-seo/blob/main//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`](https://github.com/every-app/open-seo/blob/main//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.