How to Get Domain Overview Using OpenSEO MCP: A Complete Guide

The OpenSEO MCP exposes a get_domain_overview tool that queries DataForSEO Labs to return organic traffic estimates, keyword counts, top keywords, and top pages for any domain.

OpenSEO MCP (Message-Chat-Protocol) provides a structured way to access SEO intelligence through tool-based interfaces. The domain overview functionality sits at the intersection of the MCP server layer and the DataForSEO Labs API. This guide breaks down exactly how the tool works, where it's implemented, and how to call it from multiple contexts.

What the Domain Overview Tool Returns

When you invoke get_domain_overview, the tool aggregates data from DataForSEO Labs' domain_rank_overview/live endpoint and returns a structured payload containing:

• Estimated organic traffic for the entire domain including subdomains
• Total organic keyword count the domain currently ranks for
• Top-ranking keywords with position, search volume, CPC, difficulty score, and search intent
• Top organic pages with URL, position, and traffic estimates per page

The response includes both machine-readable structured data and a human-readable summary string for direct display.

Where the Domain Overview Is Implemented

The tool implementation spans three core files in the OpenSEO codebase:

File Path	Purpose
src/server/mcp/tools/get-domain-overview.ts	Main tool implementation: input validation, domain normalization, API orchestration, response transformation, and caching
src/server/lib/dataforseo/labs.ts	Low-level DataForSEO Labs API client that handles domain_rank_overview calls
src/server/mcp/server.ts	MCP server registration that exposes get_domain_overview as a callable tool

According to the OpenSEO source code, the tool follows a strict input-output contract defined with Zod schemas. The handler normalizes the input domain (stripping www. prefix and lowercasing), enforces a 12-hour cache to avoid redundant API charges, and shapes the raw DataForSEO envelope into a clean, predictable JSON structure.

How to Call the Domain Overview Tool

Built-in UI Method

Navigate to /features/domain-overview in the OpenSEO web application. Enter a domain like example.com and click Get Overview. The frontend at web/src/routes/_marketing/features/domain-overview.tsx automatically constructs and sends the MCP request, then renders the returned metrics.

Direct HTTP API Call

For programmatic access, POST to the MCP endpoint with the tool name and input parameters:

curl https://openseo.so/api/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "get_domain_overview",
    "input": { "target": "example.com" }
  }'

The JSON response follows this structure:

{
  "structuredContent": {
    "overview": {
      "domain": "example.com",
      "traffic": 12345,
      "keywordCount": 678,
      "topKeywords": [
        {
          "keyword": "example keyword",
          "position": 1,
          "volume": 5000,
          "cpc": 1.23,
          "difficulty": 45,
          "intent": "informational"
        }
      ],
      "topPages": [
        {
          "url": "https://example.com/",
          "position": 1,
          "traffic": 3000
        }
      ]
    },
    "summary": "Domain overview for example.com: ~12k organic traffic, ranking for 678 keywords."
  },
  "status": "ok"
}

JavaScript SDK Integration

If you're using the OpenSEO SDK in a Node.js or browser environment:

import { createMcpClient } from '@open-seo/sdk';

const client = createMcpClient({ baseUrl: 'https://openseo.so/api' });

async function getDomainOverview(domain) {
  const result = await client.callTool('get_domain_overview', { target: domain });
  console.log(result.structuredContent.overview);
  return result.structuredContent.overview;
}

getDomainOverview('example.com');

The callTool method handles request serialization, error mapping, and response parsing automatically.

Server-Side TypeScript Function

For backend integrations using TanStack Server or similar frameworks:

import { getDomainOverviewTool } from '@/server/mcp/tools/get-domain-overview';
import { z } from 'zod';

export async function fetchDomainOverview(domain: string) {
  const input = { target: domain };
  
  // Validate input matches the tool's Zod schema
  const validated = z.object({ 
    target: z.string().min(1) 
  }).parse(input);
  
  // Call the tool handler directly
  const { structuredContent } = await getDomainOverviewTool.handler(validated);
  return structuredContent.overview;
}

This pattern bypasses HTTP overhead when calling from within the same process and gives you full type safety through the tool's exported interfaces.

Input Validation and Domain Normalization

The get_domain_overview tool enforces strict input rules as implemented in src/server/mcp/tools/get-domain-overview.ts:

• Required parameter: target (string, minimum 1 character)
• Normalization: Strips www. prefix and converts to lowercase
• No protocol handling: Pass example.com not https://example.com

Invalid inputs trigger Zod validation errors before any external API call occurs, preventing wasted credits on malformed requests.

Caching and Billing Considerations

As defined in src/shared/billing-credit-features.ts, the domain_overview feature consumes credits per unique domain lookup. The tool implements 12-hour response caching keyed by normalized domain. Repeated calls for the same domain within this window return cached data without hitting DataForSEO or deducting additional credits.

Cache invalidation is automatic; no manual purge is required. For fresh data, wait for the TTL expiration or pass a cache-bypass flag if your MCP client configuration supports it.

Summary

• Use get_domain_overview from OpenSEO MCP to retrieve comprehensive domain intelligence
• Call via UI, HTTP POST, JavaScript SDK, or direct server-side import depending on your architecture
• Input requires only a target domain; normalization handles www. and case automatically
• Responses include traffic estimates, keyword counts, top keywords with intent, and top pages
• 12-hour caching protects against redundant API charges per unique domain

Frequently Asked Questions

What input format does the domain overview tool accept?

The get_domain_overview tool accepts a single required string parameter target. Pass the domain without protocol—example.com rather than https://example.com. The implementation in src/server/mcp/tools/get-domain-overview.ts automatically strips www. prefixes and lowercases the input before processing.

How long are domain overview results cached?

Results are cached for 12 hours based on the normalized domain key. This cache duration prevents duplicate DataForSEO API charges when the same domain is queried multiple times. The caching logic lives in the tool handler and applies to all invocation methods—UI, HTTP, SDK, and server-side.

Can I call the domain overview tool without the OpenSEO web interface?

Yes. The tool is fully accessible via HTTP POST to /api/mcp with the JSON payload {"tool": "get_domain_overview", "input": {"target": "example.com"}}. You can also import getDomainOverviewTool directly from src/server/mcp/tools/get-domain-overview in server-side TypeScript code for zero-overhead internal calls.

What billing credits does a domain overview request consume?

The domain_overview feature is listed in src/shared/billing-credit-features.ts and consumes credits per unique uncached lookup. Cache hits within the 12-hour window consume no additional credits. Exact credit costs depend on your OpenSEO plan and are enforced at the MCP server layer before tool execution.

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