# How AI Agents Query SEO Data Using OpenSEO's MCP Server: A Complete Guide

> Learn how AI agents query SEO data via OpenSEO's MCP server. Access domain overviews, keyword research, backlinks, and GSC metrics with JSON-RPC 2.0 requests. Complete guide available.

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

---

**AI agents query SEO data through OpenSEO's Model Context Protocol (MCP) server by sending authenticated JSON-RPC 2.0 requests to the `/mcp` endpoint, which exposes domain overviews, keyword research, backlink profiles, and Google Search Console metrics as callable tools.**

OpenSEO's **MCP server** provides a standardized interface for AI systems to access live SEO intelligence. The implementation follows the [Model Context Protocol](https://modelcontextprotocol.io) specification, enabling any HTTP-capable client—from Claude Code to custom Python scripts—to retrieve structured search data programmatically.

## Setting Up MCP Server Authentication

Before querying data, agents must authenticate with the **MCP scope** (`MCP_SCOPE`). OpenSEO supports two authentication methods:

- **OAuth tokens** with the MCP scope included
- **Personal API keys** passed via the `Authorization: Bearer` header or `x-api-key` header

Users generate API keys through the OpenSEO web interface. All subsequent requests must include valid credentials.

The transport layer enforces this in [`src/server/mcp/transport.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.ts) (lines 49-62), where scope validation rejects unauthorized requests:

```typescript
// src/server/mcp/transport.ts
if (!result.data[MCP_AUTH_CONTEXT_PROP].scopes.includes(MCP_SCOPE)) {
  return new Response("MCP scope required", { status: 403 });
}

```

## MCP Server Architecture and Tool Registration

The server instance is created in [`src/server/mcp/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/server.ts) (lines 28-45), where each SEO tool registers its input schema, output schema, and handler function:

```typescript
// src/server/mcp/server.ts
export function createOpenSeoMcpServer(authProps: McpProps) {
  const server = new McpServer({ name: "OpenSEO MCP", … });
  const register = <Input extends ToolSchema>(tool: OpenSeoToolDefinition<Input>) =>
    registerOpenSeoTool(server, tool, authProps);
  register(getDomainOverviewTool);   // ← domain metrics
  register(getBacklinksProfileTool); // ← link analysis
  register(researchKeywordsTool);    // ← keyword discovery
  register(getSearchConsolePerformanceTool); // ← GSC data
  // … additional tools
  return server;
}

```

This pattern ensures **type-safe tool definitions** with automatic validation of request parameters against declared schemas.

## Querying SEO Data: The JSON-RPC Flow

AI agents interact with the MCP server through **stateless HTTP POST requests** to `https://app.openseo.so/mcp`. Each request follows the JSON-RPC 2.0 specification with four required fields:

| Field | Description | Example |
|-------|-------------|---------|
| `jsonrpc` | Protocol version | `"2.0"` |
| `method` | Tool name to invoke | `"get_domain_overview"` |
| `params` | Tool-specific arguments | `{"domain": "example.com"}` |
| `id` | Request correlation identifier | `1` |

The transport handler in [`src/server/mcp/transport.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.ts) routes validated requests to the appropriate tool handler, executes the underlying database or third-party API call, and returns the structured response.

### Available MCP Tools

According to [`web/content/docs/mcp.md`](https://github.com/every-app/open-seo/blob/main/web/content/docs/mcp.md), the server exposes these primary tools:

- **`get_domain_overview`** – Aggregate authority, traffic estimates, and rank distribution
- **`get_backlinks_profile`** – Referring domains, anchor text distribution, link velocity
- **`research_keywords`** – Search volume, difficulty scores, SERP features, related keywords
- **`get_search_console_performance`** – Clicks, impressions, CTR, and position data from Google Search Console
- **`get_serp_analysis`** – Real-time search result page structure and competitor positioning

## Code Examples: Querying from Different Environments

### Direct HTTP with curl

```bash
curl -X POST https://app.openseo.so/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer oseo_YOUR_KEY" \
  -d '{
        "jsonrpc":"2.0",
        "method":"get_domain_overview",
        "params":{"domain":"example.com"},
        "id":1
      }'

```

### Node.js with native fetch

```javascript
const response = await fetch('https://app.openseo.so/mcp', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer oseo_YOUR_KEY',
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'research_keywords',
    params: { keyword: 'cloud hosting', language: 'en' },
    id: 42,
  }),
});

const result = await response.json();
console.log(result.result); // → array of keyword metrics

```

### Python with requests

```python
import requests, json

payload = {
    "jsonrpc": "2.0",
    "method": "get_backlinks_profile",
    "params": {"domain": "example.com"},
    "id": 7,
}
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer oseo_YOUR_KEY",
}
r = requests.post("https://app.openseo.so/mcp", headers=headers, data=json.dumps(payload))
print(r.json()["result"])

```

## Connecting AI Coding Assistants

### Claude Code (built-in MCP client)

```bash
claude mcp add --transport http --scope user openseo https://app.openseo.so/mcp \
  --header "Authorization: Bearer oseo_YOUR_KEY"

```

See steps 24-26 in [`web/content/docs/mcp.md`](https://github.com/every-app/open-seo/blob/main/web/content/docs/mcp.md) for additional configuration options.

### Cursor (via [`mcp.json`](https://github.com/every-app/open-seo/blob/main/mcp.json))

```json
{
  "mcpServers": {
    "openseo": {
      "url": "https://app.openseo.so/mcp",
      "headers": {
        "Authorization": "Bearer oseo_YOUR_KEY"
      }
    }
  }
}

```

Lines 45-52 of [`web/content/docs/mcp.md`](https://github.com/every-app/open-seo/blob/main/web/content/docs/mcp.md) document the full Cursor configuration schema.

## Response Format and Error Handling

Successful tool invocations return a JSON-RPC response with the `result` field containing typed output data. Errors propagate through standard JSON-RPC error objects with descriptive messages:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "domain": "example.com",
    "authority_score": 67,
    "organic_traffic": 125000,
    "backlinks_total": 45000
  },
  "id": 1
}

```

Because the server is **stateless**, clients must include complete context in each request. No session cookies or connection state persist between calls.

## Key Implementation Files

| File | Purpose |
|------|---------|
| [`src/server/mcp/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/server.ts) | Server instantiation and tool registration |
| [`src/server/mcp/transport.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.ts) | HTTP routing, CORS, authentication, request forwarding |
| [`web/content/docs/mcp.md`](https://github.com/every-app/open-seo/blob/main/web/content/docs/mcp.md) | Integration guides for Claude, Cursor, Codex, and direct API usage |

## Summary

- **OpenSEO's MCP server** exposes SEO tools through a standardized JSON-RPC interface at `https://app.openseo.so/mcp`
- **Authentication requires** the MCP scope via OAuth tokens or personal API keys (`oseo_` prefix)
- **Tool registration** in [`src/server/mcp/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/server.ts) provides type-safe, schema-validated endpoints for domain analysis, keyword research, backlink data, and Search Console metrics
- **Any HTTP client** can query the server—no special SDK required—making it compatible with Claude Code, Cursor, custom scripts, and direct API integration
- **Stateless architecture** ensures predictable, reproducible behavior across AI agent sessions

## Frequently Asked Questions

### What is MCP and why does OpenSEO use it?

The **Model Context Protocol (MCP)** is an open standard for exposing contextual tools to AI systems. OpenSEO implements MCP to allow any compatible client—Claude Code, Cursor, or custom implementations—to discover and invoke SEO analysis tools without proprietary SDKs. This standardization reduces integration friction and enables composable AI workflows.

### How do I obtain an API key for MCP access?

Navigate to the OpenSEO web interface, access your account settings, and generate a **personal API key** with MCP scope. The key begins with `oseo_` and should be treated as a secret. Pass it in the `Authorization: Bearer` header for all MCP requests, or configure it in your AI assistant's MCP settings.

### Can I use the MCP server without Claude or Cursor?

Yes. The MCP server is a **standard HTTP JSON-RPC service**. Any environment capable of POST requests—including Python scripts, Node.js applications, Bash with curl, or browser-based fetch calls—can query SEO data directly. The protocol intentionally avoids vendor-specific dependencies.

### What happens if my MCP request fails scope validation?

The transport layer in [`src/server/mcp/transport.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.ts) returns HTTP **403 Forbidden** with the message "MCP scope required" when authentication is missing or insufficient. Verify your API key is active, includes the MCP scope, and is formatted correctly in the `Authorization` header.