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

> Learn how to get domain overview with OpenSEO MCP. Explore organic traffic estimates, keyword counts, top keywords, and pages using this powerful tool.

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

---

**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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/server/lib/dataforseo/labs.ts) | Low-level DataForSEO Labs API client that handles `domain_rank_overview` calls |
| [`src/server/mcp/server.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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:

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

```json
{
  "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:

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

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