Documentation Center

This is the developer and integration documentation for MCP, API authentication, parameters, cost estimates, and responses. If you are connecting SEO Agent for the first time, start with the beginner setup guide.

Getting Started Guide

SEO Agent provides capabilities in two ways: MCP lets Codex and other AI tools call SEO capabilities from natural-language goals, while the API supports scripts, client reports, and internal systems. Both use the same SEO Agent API Key and public billing rules.

Hands-on Tutorial

Step 1: Register an Account

Visit SEO Agent Homepage, click the "Sign Up / Log In" button in the top right corner, fill in your email, password, and confirm password to complete registration. The registration process is simple and fast, taking less than 1 minute.

Step 2: Add Balance

After logging in, open the Pricing page, select a top-up amount, and complete payment. SEO Agent uses a pay-as-you-go model with a minimum top-up of $30. Your balance remains valid and does not expire.

Step 3: Start Using

To start SEO tasks in everyday language inside Codex, configure MCP. To integrate scripts, client reports, or internal systems, use the API. See the How to Use guide for the full beginner setup.

API Overview

SEO Agent provides a complete REST API for scripts, client reports, and internal systems. MCP and API share the same SEO Agent API Key: MCP is designed for automatic calls from AI tools, while the API is designed for stable calls from systems and scripts. Both return standardized data and billing details; Codex or your own AI workflow can turn those results into a complete consultant report.

Recommended Call Flow

1. On the profile page, create an API Key and select the permitted API scope.
2. Decide how to integrate: MCP for AI tools, API for scripts, reports, and internal systems.
3. Before making a formal query, first call /api/dev/estimate or pass in dryRun: true to estimate the cost.
4. After confirming the parameters, market, and balance, execute the formal query, and from the response's data and billing read the results and billing information.

Supported API Endpoints

• MCP Integration - Let Codex and other AI tools call SEO Agent based on your goal, without the need to manually remember endpoint paths.
• API Integration - Integrate standardized SEO data into scripts, client reports, and internal systems
• GEO / AI Search Visibility - Query Google AI Overview and ChatGPT for current mentions, top sources, historical trends, new/lost, multi-target comparison, and brand-category landscape
• GEO Deep Audit - Check page citability, AI crawlers, llms.txt, Schema, and brand platform recommendations, with optional PDF report output
• Keyword Research - Query search volume, competition, search intent, and related keywords for seed keywords
• In-depth Keyword Research - Complete KD, CPC, trends, question keywords, commercial value, and keyword grouping
• Domain-specific keyword opportunities - Based on the target domain's current rankings, decide whether to optimize existing pages or create new pages
• Domain Keywords - Query the current organic ranking keywords for a specified domain
• Competitor Keyword Gap - Compare keyword gaps between your website and competitor domains
• Competitor keyword strategy analysis - Enter seed keywords to compile high-search-volume keywords from top-ranking peers and competitors
• Keyword ranking lookup - Query the organic ranking of a specified domain for a given keyword
• On-site audit - Use SEO Agent's built-in crawler to audit technical SEO and on-site SEO
• GSC Search Performance and Diagnostics - Read clicks, impressions, CTR, rankings, content decay, keyword cannibalization, and action plans for authorized sites
• GA4 Traffic Quality Diagnostics - Read sessions, channels, landing pages, engagement rate, bounce rate, and key events for authorized media resources, and output landing page opportunities, channel diagnostics, and action plans
• Account Balance - Query the account balance and available quota for the current API Key
• Spending History - Query historical API call consumption records

Authentication Methods

All API requests must include an API Key in the request header for authentication. You can create and manage API Keys on your personal settings page.

Example Code

curl -X POST https://www.seoagent.vip/api/dev/keyword-research \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "running shoes",
    "location": "United States",
    "language": "English"
  }'

Cost Estimate API

Estimate the maximum cost before making a formal query. No query is executed, and no charge is incurred. Supports cost estimation for all query-type APIs.

Example: Estimate to Formal Call

# 1. Estimate the cost first
curl -X POST https://www.seoagent.vip/api/dev/estimate \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "domain-keyword-opportunities",
    "params": {
      "domain": "example.com",
      "keyword": "running shoes",
      "location": "United States",
      "language": "English",
      "limit": 10
    }
  }'

# 2. Make the formal query after confirmation
curl -X POST https://www.seoagent.vip/api/dev/domain-keyword-opportunities \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "example.com",
    "keyword": "running shoes",
    "location": "United States",
    "language": "English",
    "limit": 10
  }'

Keyword Research API

Query the search volume, competition, search intent, and related keywords for a seed keyword, helping you determine which keywords are worth prioritizing.

Deep Keyword Research API

On top of basic keyword research, it adds keyword difficulty, CPC, trends, question keywords, commercial value, suggested page types, and keyword grouping. Suitable for content planning and page matrix creation.

Main response fields

• keywords: Keyword details, including search volume, CPC, competition, KD, trend score, question keywords, commercial score, suggested page type, and priority.
• groups: Keyword grouping, including group name, main keyword, total search volume, average difficulty, number of commercial keywords, number of question keywords, and recommended page type.
• history: Keyword historical trend summary.

Domain Personalized Keyword Opportunity API

Enter a target domain and seed keyword. SEO Agent combines keyword expansion data with the target domain's existing organic rankings to determine which keywords the website should prioritize, whether matching pages already exist, and whether to recommend optimizing existing pages or creating new pages.

Main response fields

• keywords: Personalized opportunity keywords, including opportunity score, current ranking, matching page, difficulty fit score, recommended action, and P0/P1/P2 priority.
• groups: Keyword groups merged by topic, helping determine how many pages to create.
• domainMetrics: Ranking capability metrics from the target domain's current sample.

Domain Keyword API

Query the current organic ranking keywords of a specified domain to understand the website's keyword coverage.

Competitor Keyword Gap API

Compare the keyword gap between your website and a competitor domain to find keyword opportunities where the competitor ranks but you don't.

Competitor Keyword Strategy API

Enter a seed keyword to automatically compile up to 5 top-ranking peer websites and up to 10 high-search-volume ranking keywords per competitor.

Ranking Query API

Query the organic ranking position of a specified domain for a given keyword.

GEO Visibility API

Use the new LLM Mentions to query current mentions, target metrics, high-frequency source domains and pages for Google AI Overview or ChatGPT. Can be via platform Select google or chat_gpt, via lite: true use lightweight query.

GEO Trends, Comparison, and Brand Landscape API

The following endpoints all use the new LLM Mentions and no longer call the old endpoints. The default platform is google; specify chat_gpt only supports United States / English.

{
  "domain": "yourdomain.com",
  "platform": "google",
  "dateFrom": "2026-01-01",
  "dateTo": "2026-07-01",
  "location": "United States",
  "language": "English"
}

{
  "targets": ["yourdomain.com", "competitor-a.com", "competitor-b.com"],
  "platform": "google",
  "location": "United States",
  "language": "English"
}

GEO Deep Audit API

Audit the GEO foundation of a single website or page, including page citability, AI crawler access status, llms.txt structure, Schema suggestions, brand platform suggestions, and an overall score. llms.txt It is a supplementary explanatory document and does not mean that AI search will necessarily cite it; the report will separate detected facts from optimization suggestions.

Site Audit API

Use SEO Agent's built-in crawler, first read robots.txt and Sitemap to estimate the number of pages, then audit website pages, titles, descriptions, H1, canonical, internal/external links, image alt, response speed, and indexing issues. For 100 pages or fewer, it executes synchronously after fee confirmation; for more than 100 pages, it automatically creates a background asynchronous task after fee confirmation.

Site Audit (Async) API

Websites with more than 100 pages use asynchronous site audit: SEO Agent continuously crawls Sitemap pages in the background and immediately returns a task ID. The returned result explains the estimated time, maximum fee, and how to query; it supports receiving completion notifications via callbackUrl, or obtaining real-time progress and the final report through the query API.

GSC Search Performance and Diagnostics API

Read GSC search performance data for the user's authorized properties, used to integrate real clicks, impressions, CTR, average position, content decay, keyword cannibalization, and prioritized action plans into Codex, scripts, or internal reports. Before using, you must first complete the GSC connection on the profile page and check the corresponding GSC permissions when creating an API Key.

curl -X POST https://www.seoagent.vip/api/dev/gsc-search-analytics \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dimensions": ["query", "page"],
    "startDate": "2026-06-01",
    "endDate": "2026-06-28",
    "rowLimit": 1000
  }'

GA4 Traffic Quality Diagnostic API

Read GA4 data for the user's authorized properties, used to integrate sessions, users, channels, landing pages, engagement rate, bounce rate, key events, and conversion attribution diagnostics into Codex, scripts, or internal reports. Before using, you must first complete the GA4 connection on the profile page and check the corresponding GA4 permissions when creating an API Key.

curl -X POST https://www.seoagent.vip/api/dev/ga4-report \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dimensions": ["landingPagePlusQueryString"],
    "metrics": ["sessions", "engagementRate", "bounceRate", "keyEvents"],
    "startDate": "2026-06-01",
    "endDate": "2026-06-28",
    "limit": 100
  }'

Account Balance API

Query the account balance, available credit, and plan information associated with the current API Key.

Usage Records API

Query the historical usage records of API calls, including endpoint type, call time, charged amount, and call status.

What is an SEO workflow?

An SEO workflow breaks a natural-language task into multiple sequential steps. For example, when you say “create a content set around CRM software suitable for small businesses,” SEO Agent first looks up keywords and search results, then plans core pages, supporting articles, and internal links, rather than directly writing an article from scratch.

You don't need to remember professional commands. Just describe the website, product or topic, and target market, and the system will choose an appropriate workflow; if necessary information is missing, it will ask you first. After query, analysis, and plan generation are complete, the workflow pauses at the confirmation stage. Only when you approve the results and explicitly give approval will the system continue to modify files or publish to an already connected website.

A complete usage example

1. In the Codex conversation, say: “Help me plan a content cluster around CRM software suitable for small businesses.”
2. SEO Agent looks up keywords and search results, and returns core pages, supporting articles, search intent, and internal link suggestions.
3. You review the results. If adjustments are needed, you can continue: “Change the focus to teams of fewer than 10 people in the United States.”
4. After approval, say: “Confirm this plan and publish the first article to my connected WordPress draft folder.”
5. After publishing, the system returns the page link; if monitoring has been set up, it will also re-check on schedule and send notifications.

Five common workflow templates

Also possible after logging in. GET /api/workflow-templates Read template, approve. POST /api/workflows Create a workflow, and use POST /api/workflows/{id}/approve Approve to continue execution. Usually there is no need to manually call these APIs; Codex automatically creates and advances workflows based on the conversation.

Approval, publishing, and scheduled monitoring

Connect WordPress or CMS

1. Log in to SEO Agent and go to “Profile”.
2. Find “Publishing Connection” and select WordPress or Generic CMS.
3. Enter the website address and the dedicated access credentials provided by that website, then click “Test Connection”.
4. After the test succeeds, return to the Codex conversation to create a content workflow. The system will still wait for your confirmation before publishing.

It is recommended to create a separate publishing account with restricted permissions for SEO Agent and prioritize publishing as drafts. After deleting the connection, SEO Agent will no longer retain the access entry for that connection.

Scheduled monitoring and notifications

After completing a workflow, you can set it as a scheduled task. For example, review technical issues weekly, and check keyword and GEO visibility changes monthly. The system will copy the original workflow’s goals and inputs to re-execute, and write the status of completed, failed, or awaiting manual confirmation to the notification center; after configuring an email service, it can also send email reminders.

Relevant APIs include POST /api/workflow-schedules、GET /api/workflow-schedules and GET /api/notifications Scheduled tasks will not skip approval: when page modifications or formal publishing are involved, manual confirmation is still required according to the workflow settings.

MCP Overview

MCP (Model Context Protocol) is a protocol that allows AI tools to directly call external capabilities. With MCP integration, MCP-capable AI tools (such as Codex) can automatically understand your goals, proactively call SEO Agent's standardized data capabilities, and complete continuous workflows including querying, organizing, and preparing analysis drafts. For standalone website sellers, SEO agencies, and foreign trade businesses, its value is to reduce the time spent manually entering multiple tools to check data, copy, and organize tables.

MCP Advantages

• Automated workflows - AI tools automatically call capabilities based on goals, with no need to manually switch tools
• Better suited to SEO agencies for batch delivery - Can organize multiple clients' keyword, GEO, competitor, and authorized data into drafts
• Better suited to standalone website growth - Can continuously find page opportunities around product keywords, target countries, and competitors
• Natural language interaction - Describe tasks in natural language, and the AI executes automatically after understanding

Supported MCP tools

• seoagent_keyword_research: Lightweight keyword research, suitable for quickly checking search volume, competition, intent, and related keywords.
• seoagent_keyword_intelligence: In-depth keyword research, returns KD, CPC, trends, question keywords, commercial value, and keyword grouping.
• seoagent_domain_keyword_opportunities: Domain-specific keyword opportunities, combined with the domain's existing rankings to determine whether to optimize existing pages or create new pages.
• seoagent_domain_keywords: Query the existing organic ranking keywords for a specified domain.
• seoagent_competitor_gap: Compare the keyword gap between our domain and competitor domains.
• seoagent_competitor_keyword_strategy: Based on seed keywords, compile high-search-volume keywords from top-ranked peers and competitors.
• seoagent_serp_rank_query: Query the ranking position of a specified domain for a specified keyword.
• seoagent_geo_visibility: Query the GEO / AI search visibility of a brand, topic, or domain.
• seoagent_geo_visibility_history: Query historical AI visibility trends.
• seoagent_geo_visibility_delta: Query the change in AI visibility.
• seoagent_geo_visibility_new_lost: Query new and lost AI mentions.
• seoagent_geo_visibility_comparison: Compare AI visibility for up to 10 targets.
• seoagent_geo_brand_landscape: Query high-frequency AI brands and brand category landscape.
• seoagent_geo_deep_audit: Perform a deep GEO audit, returning page citability, AI crawlers, llms.txt, Schema, and an optional PDF report.
• seoagent_site_audit: First read the Sitemap to return estimated page count, maximum cost, and estimated time; within 100 pages, run a synchronous audit after confirmation; over 100 pages, switch to background asynchronous batch audit after confirmation.
• seoagent_get_site_audit_task: Use the task ID to query async audit progress; after task completion, read the final report containing a completeness statement.
• seoagent_gsc_sites: Query the authorized GSC site list and default site.
• seoagent_gsc_search_analytics: Query GSC search performance, including clicks, impressions, CTR, and average position.
• seoagent_gsc_keyword_opportunities: Identify high-impression low-CTR and Quick Win keyword opportunities.
• seoagent_gsc_page_opportunities: Identify page opportunities that require priority optimization.
• seoagent_gsc_performance_summary: Compare GSC performance between the current period and the previous period, outputting sources of growth and decline.
• seoagent_gsc_content_decay: Discover pages and queries with significantly declining clicks or rankings.
• seoagent_gsc_cannibalization: Identify keyword cannibalization risks where multiple pages target the same query.
• seoagent_gsc_action_plan: Generate a P0/P1/P2 priority action list based on comprehensive GSC diagnostic results.
• seoagent_ga4_properties: Query the authorized GA4 property list and default property.
• seoagent_ga4_report: Query GA4 report data, including sessions, users, views, engagement rate, bounce rate, and key events.
• seoagent_ga4_traffic_summary: Summarize GA4 traffic quality, channel, device, and country performance.
• seoagent_ga4_landing_page_opportunities: Identify landing page opportunities with visits but weak conversion or follow-through.
• seoagent_ga4_channel_insights: Diagnose channel traffic quality and key event performance.
• seoagent_ga4_action_plan: Synthesize GA4 diagnostic results to generate a P0/P1/P2 priority action list.
• seoagent_search_consultant_knowledge: On-demand retrieval of SEO consultant methodology, scenario judgment, and official practice summaries; can be automatically used in strategy, diagnostic, and reporting tasks. MCP will require AI to present results in natural, easy-to-understand client language rather than directly displaying tool data.
• seoagent_get_consultant_knowledge_card: Read a retrieved knowledge card when finer decision boundaries, execution workflows, or acceptance criteria are needed.
• seoagent_estimate: Estimate costs and cache hit status before making a formal query.

MCP Configuration Guide

Prerequisites

1. Have registered an SEO Agent account and completed the initial top-up.
2. Created an API Key on the personal settings page.
3. Use an AI tool that supports the MCP protocol (such as Codex).

Recommended: Complete configuration in a Codex conversation.

Open any trusted Codex conversation and the following YOUR_SEO_AGENT_API_KEY After replacing with your own SEO Agent API Key, send it directly. Codex will write the remote MCP configuration to your local machine's ~/.codex/config.toml, retaining the existing MCP configurations.

Please add the SEO Agent remote MCP to my local Codex.

Only modify ~/.codex/config.toml, and do not delete or overwrite existing configurations;
Append the following configuration to the end of the file, and check the TOML syntax after writing:

[mcp_servers.seoagent]
enabled = true
url = "https://www.seoagent.vip/mcp"

[mcp_servers.seoagent.http_headers]
Authorization = "Bearer YOUR_SEO_AGENT_API_KEY"

Do not echo my API Key in your reply. After completion, tell me whether I need to start a new conversation or restart Codex for it to load.

If you prefer to edit the configuration file yourself, you can append the following content to ~/.codex/config.toml. This is the remote MCP format currently used by Codex, not the old mcpServers JSON or local Node startup script format.

[mcp_servers.seoagent]
enabled = true
url = "https://www.seoagent.vip/mcp"

[mcp_servers.seoagent.http_headers]
Authorization = "Bearer YOUR_SEO_AGENT_API_KEY"

Codex Integration Guide

After completing the configuration in a Codex conversation, you can use natural language to have Codex call SEO Agent to complete tasks such as standalone website SEO, GEO, keyword research, and client report drafts.

Loading and Verification

1. After letting Codex complete the configuration, start a new conversation; if the tools do not appear, restart Codex.
2. In the new conversation, send: Check whether the SEO Agent MCP is connected, and only list the names of the available SEO tools.
3. After confirming the connection, send real business tasks; for the first time, it is recommended to use a small-scope keyword or domain query to verify permissions, market, and balance.

Using Codex

After configuration, you can directly ask questions in Codex, for example:

• "Help me analyze the SEO opportunities for the standalone website example.com in the U.S. English market"
• "Check the search volume and competition for the keyword running shoes, and determine whether it is suitable for a product page or a blog page"
• "Deep-dive analysis of running shoes keyword groupings, commercial keywords, and question keywords"
• "Analyze example.com's personalized keyword opportunities around running shoes in the U.S. English market"
• "Compare the content gap between example.com and competitor.com"
• "Perform a site audit for example.com"
• "Using my connected GSC data, find keyword opportunities with high impressions, low clicks, and rankings 8-20 in the last 28 days"
• "Using my connected GA4 data, find landing pages that had visits but weak key events in the last 28 days"

FAQ

Are there rate limits on API calls?

Yes. The default API call rate limit is 240 calls per minute. If you need a higher rate limit, please contact our sales team for a custom enterprise plan.

How can I estimate API call costs?

You can use /api/dev/estimate endpoint to estimate call costs, and you can also set it during the call. dryRun: true Parameters for getting estimated costs without actually executing.

Are API Keys secure?

API Keys are stored encrypted. The full key is only displayed once at creation and cannot be viewed later. You can set different API permissions (scope), consumption limits, and validity periods for each key to reduce risk.

Which programming language SDKs are supported?

Currently, we provide a REST API. You can call it using any programming language that supports HTTP requests. The official SDK is under development. Stay tuned!