xSeek/Docs
Back to documentation
Reference

xSeek MCP server reference.

Endpoint, auth, scopes, tools and limits for connecting an AI assistant or coding agent to xSeek.

Updated Oct 20265 min readFor developers & agents

Endpoint

MCP server
https://www.xseek.io/api/mcp

Streamable HTTP, stateless: every request is a POST with Authorization: Bearer <token>. The server sends its own instructions on initialize and exposes one prompt, setup_xseek. The same instructions are public at /agent-instructions.md. Discovery: /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server.

Authentication

Two kinds of bearer token are accepted.

OAuth 2.1 (assistants)

Dynamic client registration, authorization code with PKCE (S256). An unauthenticated call returns 401 with a WWW-Authenticate header pointing at the resource metadata, which is how ChatGPT, Claude and Cursor start the sign-in. The consent page lets the person pick the workspace and shows every scope requested.

  • Access token xstok_...: 30 days.
  • Refresh token: 90 days, single use, rotated on every refresh. Reusing an old one revokes the whole chain.
  • Authorization code: 5 minutes.
  • No scope requested: the default set below. Unknown scopes are dropped.
  • A call without the scope a tool needs returns 403 with error="insufficient_scope" and the scopes to request.

API key (scripts, CI, the CLI)

An aist_... key from API Keys works as the bearer token too, limited to the permissions picked when it was created. The CLI gets its key through device sign-in.

Client config

Per-client steps, or the raw config for any MCP client.

  1. 1In ChatGPT, open Settings, then Apps and Connectors.
  2. 2Click Create. If you don't see it, turn on developer mode under Advanced settings first.
  3. 3Name it xSeek, paste the xSeek address and pick OAuth.
  4. 4Sign in on xSeek and pick your workspace.
xSeek address
https://www.xseek.io/api/mcp

Custom connectors depend on your ChatGPT plan and workspace settings. If you can't add one, use another assistant or set up in the browser.

Codex
codex mcp add xseek --url https://www.xseek.io/api/mcp

Then run codex mcp login xseek.

mcp.json (Cursor, VS Code, Claude Desktop, others)
{
  "mcpServers": {
    "xseek": {
      "type": "http",
      "url": "https://www.xseek.io/api/mcp"
    }
  }
}

Setup flow

The order the server instructions give the agent. get_setup_status returns nextStep.tool after every step, so a half-finished setup resumes where it stopped.

  1. get_setup_status; create_website if there is none.
  2. analyze_website (and rank_keywords for other keywords), then the agent shows the whole draft, buyer keywords ranked by value, and waits for a yes.
  3. update_brand_profile, set_competitors, set_audiences with one topic per keyword, add_knowledge.
  4. suggest_prompts: one question per keyword, plus Alternatives and Integrations. Then add_prompts (at most plan.promptAllowance).
  5. start_first_run. When nextStep.tool is null, the agent reports and ends its turn.
  6. connect_google; in a code repo, get_tracking_setup, deploy, then verify_tracking with sendTestVisit: true.
Prompt to start it
Set up xSeek for my company. Our website is [your website]. Show me the draft before you save it.

Tools

Scope is what the token needs. Tools marked read change nothing. Every tool that takes a website checks it belongs to the token's workspace.

Setup

ToolScopeWhat it does
get_setup_statuswebsites:read · readChecklist, next tool to call, plan and promptAllowance, dashboard link. Pass websiteId when the workspace has several sites.
create_websitewebsites:createAdds the website to the workspace.
analyze_websitewebsites:read · readReads the homepage and drafts name, offering, market, competitors, audiences with buyer keywords ranked by value (searchVolume x CPC), integrations and voice. Saves nothing.
rank_keywordswebsites:read · readPrices buyer keywords and their agency or services variants in one market, ranked by value. Saves nothing.
update_brand_profilebrand:writeCompany name, offering, market, language, brand voice.
set_competitorsbrand:writeCompetitors with the aliases AI engines use for them.
set_audiencesbrand:writeAudiences and their topics, one topic per buyer keyword, each with its market.
add_knowledgebrand:writeNotes about the company the site does not say.
list_setup_datawebsites:read · readIds of audiences, topics and knowledge notes, for edits.
update_audiencebrand:writeRename or describe an audience.
update_topicbrand:writeRename a topic, change its market, include or exclude it from the score.
update_knowledgebrand:writeEdit a knowledge note.
delete_audiencebrand:writeSoft delete. Its questions stop running; past results are kept.
delete_topicbrand:writeSoft delete. Its questions stop running; past results are kept.
delete_knowledgebrand:writePermanent delete.
suggest_promptsprompts:read · readOne question per keyword topic, plus one per competitor (Alternatives) and per integration. Capped to what the free run takes. Saves nothing.
add_promptsprompts:createSaves up to 25 questions per call, with the keyword each was written from.
start_first_runprompts:createAsks the engines the tracked questions, then builds the action plan.
get_upgrade_linkwebsites:read · readBilling page link plus plans and prices. Payment happens in the browser.

Integrations

ToolScopeWhat it does
connect_googleintegrations:writeOne-time link for the person to connect Search Console and Analytics.
set_ga4_propertyintegrations:writePicks the GA4 property for the website.
get_tracking_setupintegrations:write, ai_visits:pushCode and steps for the site stack, plus a new key that can only send visits.
verify_trackingwebsites:readAI bot visits recorded; with sendTestVisit, requests the homepage as GPTBot and reports pass or fail.
search_crawler_logswebsites:read · readEvery AI bot request to the site, newest first. Search by URL, slug, bot, user agent or IP, or group by page.
check_llms_txtany · readChecks the site llms.txt.
ai_readable_scanany · readHow readable the pages are for AI crawlers.
agent_ready_scanany · readAgent readiness scan of the public site.
llms_txt_scanany · readllms.txt scan of the public site.
robots_txt_scanany · readWhich AI bots robots.txt allows or blocks.

Results and action plan

ToolScopeWhat it does
list_websiteswebsites:read · readWebsites in the workspace.
get_dashboard_snapshotwebsites:read, prompts:read · readScore, change, subjects, cited sources, sentiment in one call.
get_visibility_scorewebsites:read · readCurrent score and its factors.
list_subject_scoreswebsites:read · readScore per subject.
list_top_cited_sourceswebsites:read · readSources AI engines cite most.
list_sourceswebsites:read · readAll cited sources.
list_promptsprompts:read · readTracked questions.
get_prompt_visibilityprompts:read · readMention rate per tracked question.
add_promptprompts:createAdds one tracked question.
remove_promptprompts:updatePauses a tracked question.
list_opportunitieswebsites:read · readThe action plan, with who each action is assigned to.
get_action_resultswebsites:read, prompts:read · readMention rate before and after a completed action.
complete_actionprompts:updateMarks an action done.
dismiss_actionprompts:updateRemoves an action and frees its monthly slot.
assign_actionprompts:updateAssigns an action to a member.
keywords_researchwebsites:read · readSearch volume and difficulty for keywords.

Content Studio

ToolScopeWhat it does
get_brand_contextarticles:read · readBrand voice, audiences and knowledge.
list_articlesarticles:read · readArticles and briefs, filterable by status and action.
get_articlearticles:read · readOne article with its content.
search_contentarticles:read · readSearches the site content xSeek indexed.
get_site_pageswebsites:read · readReads the site's own pages as AI crawlers see them: schema types, meta tags, FAQ, page kind, technical issues.
push_articlearticles:writeCreates or overwrites a draft, or a brief.
update_articlearticles:writeEdits an article.
publish_articlearticles:publishPublishes to the live site. Needs articles:publish.
push_imageimages:writeUploads an image to public storage.
start_writing_agentarticles:writeRuns the xSeek writer on an action. Uses 1 monthly article.
get_writing_runarticles:read · readStatus and result of a writing run.

Scopes

ScopeGrantsDefault
ai_visits:pushSend AI visit dataask by name
ai_visits:readRead AI visit dataask by name
llm_queries:readRead AI search queriesask by name
websites:createAdd tracked websitesyes
websites:readRead websites, scores, subjects, sources, and opportunitiesyes
websites:updateChange website settingsyes
prompts:createAdd tracking promptsyes
prompts:readRead tracking prompts and sentiment evidenceyes
prompts:updateChange tracking promptsyes
articles:readRead articles and brand contextyes
articles:writeCreate or overwrite Content Studio articlesyes
articles:publishPublish articles to your websiteask by name
images:writeUpload images to public storageask by name
brand:writeEdit your brand profile, competitors, audiences and notesyes
integrations:writeConnect Google and set up trackingyes

Limits

  • Free workspace: one first run of up to 15 questions per workspace. Daily tracking and more questions need a plan (get_upgrade_link).
  • One workspace per account.
  • analyze_website and suggest_prompts: 10 calls per workspace per 24 hours.
  • rank_keywords: 30 keywords per call, 20 calls per workspace per 24 hours.
  • add_prompts: 25 per call.
  • Tracking keys: 3 enabled per website. Test visits: one per website every 2 minutes.
  • Scores, mentions, citations and actions are only written by xSeek's own measurements; no tool sets them.

Revoking access

  • In xSeek: API Keys, Connected assistants, Disconnect. Revokes every token of that client for the workspace, including pending authorization codes.
  • Claude Code: claude mcp remove xseek. ChatGPT and Claude: remove the connector in Settings.
  • Removing it only on the assistant side leaves the xSeek token valid until it expires.