xSeek MCP server reference.
Endpoint, auth, scopes, tools and limits for connecting an AI assistant or coding agent to xSeek.
Endpoint
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.
- 1In ChatGPT, open Settings, then Apps and Connectors.
- 2Click Create. If you don't see it, turn on developer mode under Advanced settings first.
- 3Name it xSeek, paste the xSeek address and pick OAuth.
- 4Sign in on xSeek and pick your workspace.
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.
Then run codex mcp login xseek.
{
"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.
get_setup_status;create_websiteif there is none.analyze_website(andrank_keywordsfor other keywords), then the agent shows the whole draft, buyer keywords ranked by value, and waits for a yes.update_brand_profile,set_competitors,set_audienceswith one topic per keyword,add_knowledge.suggest_prompts: one question per keyword, plus Alternatives and Integrations. Thenadd_prompts(at mostplan.promptAllowance).start_first_run. WhennextStep.toolis null, the agent reports and ends its turn.connect_google; in a code repo,get_tracking_setup, deploy, thenverify_trackingwithsendTestVisit: true.
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
| Tool | Scope | What it does |
|---|---|---|
| get_setup_status | websites:read · read | Checklist, next tool to call, plan and promptAllowance, dashboard link. Pass websiteId when the workspace has several sites. |
| create_website | websites:create | Adds the website to the workspace. |
| analyze_website | websites:read · read | Reads the homepage and drafts name, offering, market, competitors, audiences with buyer keywords ranked by value (searchVolume x CPC), integrations and voice. Saves nothing. |
| rank_keywords | websites:read · read | Prices buyer keywords and their agency or services variants in one market, ranked by value. Saves nothing. |
| update_brand_profile | brand:write | Company name, offering, market, language, brand voice. |
| set_competitors | brand:write | Competitors with the aliases AI engines use for them. |
| set_audiences | brand:write | Audiences and their topics, one topic per buyer keyword, each with its market. |
| add_knowledge | brand:write | Notes about the company the site does not say. |
| list_setup_data | websites:read · read | Ids of audiences, topics and knowledge notes, for edits. |
| update_audience | brand:write | Rename or describe an audience. |
| update_topic | brand:write | Rename a topic, change its market, include or exclude it from the score. |
| update_knowledge | brand:write | Edit a knowledge note. |
| delete_audience | brand:write | Soft delete. Its questions stop running; past results are kept. |
| delete_topic | brand:write | Soft delete. Its questions stop running; past results are kept. |
| delete_knowledge | brand:write | Permanent delete. |
| suggest_prompts | prompts:read · read | One question per keyword topic, plus one per competitor (Alternatives) and per integration. Capped to what the free run takes. Saves nothing. |
| add_prompts | prompts:create | Saves up to 25 questions per call, with the keyword each was written from. |
| start_first_run | prompts:create | Asks the engines the tracked questions, then builds the action plan. |
| get_upgrade_link | websites:read · read | Billing page link plus plans and prices. Payment happens in the browser. |
Integrations
| Tool | Scope | What it does |
|---|---|---|
| connect_google | integrations:write | One-time link for the person to connect Search Console and Analytics. |
| set_ga4_property | integrations:write | Picks the GA4 property for the website. |
| get_tracking_setup | integrations:write, ai_visits:push | Code and steps for the site stack, plus a new key that can only send visits. |
| verify_tracking | websites:read | AI bot visits recorded; with sendTestVisit, requests the homepage as GPTBot and reports pass or fail. |
| search_crawler_logs | websites:read · read | Every AI bot request to the site, newest first. Search by URL, slug, bot, user agent or IP, or group by page. |
| check_llms_txt | any · read | Checks the site llms.txt. |
| ai_readable_scan | any · read | How readable the pages are for AI crawlers. |
| agent_ready_scan | any · read | Agent readiness scan of the public site. |
| llms_txt_scan | any · read | llms.txt scan of the public site. |
| robots_txt_scan | any · read | Which AI bots robots.txt allows or blocks. |
Results and action plan
| Tool | Scope | What it does |
|---|---|---|
| list_websites | websites:read · read | Websites in the workspace. |
| get_dashboard_snapshot | websites:read, prompts:read · read | Score, change, subjects, cited sources, sentiment in one call. |
| get_visibility_score | websites:read · read | Current score and its factors. |
| list_subject_scores | websites:read · read | Score per subject. |
| list_top_cited_sources | websites:read · read | Sources AI engines cite most. |
| list_sources | websites:read · read | All cited sources. |
| list_prompts | prompts:read · read | Tracked questions. |
| get_prompt_visibility | prompts:read · read | Mention rate per tracked question. |
| add_prompt | prompts:create | Adds one tracked question. |
| remove_prompt | prompts:update | Pauses a tracked question. |
| list_opportunities | websites:read · read | The action plan, with who each action is assigned to. |
| get_action_results | websites:read, prompts:read · read | Mention rate before and after a completed action. |
| complete_action | prompts:update | Marks an action done. |
| dismiss_action | prompts:update | Removes an action and frees its monthly slot. |
| assign_action | prompts:update | Assigns an action to a member. |
| keywords_research | websites:read · read | Search volume and difficulty for keywords. |
Content Studio
| Tool | Scope | What it does |
|---|---|---|
| get_brand_context | articles:read · read | Brand voice, audiences and knowledge. |
| list_articles | articles:read · read | Articles and briefs, filterable by status and action. |
| get_article | articles:read · read | One article with its content. |
| search_content | articles:read · read | Searches the site content xSeek indexed. |
| get_site_pages | websites:read · read | Reads the site's own pages as AI crawlers see them: schema types, meta tags, FAQ, page kind, technical issues. |
| push_article | articles:write | Creates or overwrites a draft, or a brief. |
| update_article | articles:write | Edits an article. |
| publish_article | articles:publish | Publishes to the live site. Needs articles:publish. |
| push_image | images:write | Uploads an image to public storage. |
| start_writing_agent | articles:write | Runs the xSeek writer on an action. Uses 1 monthly article. |
| get_writing_run | articles:read · read | Status and result of a writing run. |
Scopes
| Scope | Grants | Default |
|---|---|---|
| ai_visits:push | Send AI visit data | ask by name |
| ai_visits:read | Read AI visit data | ask by name |
| llm_queries:read | Read AI search queries | ask by name |
| websites:create | Add tracked websites | yes |
| websites:read | Read websites, scores, subjects, sources, and opportunities | yes |
| websites:update | Change website settings | yes |
| prompts:create | Add tracking prompts | yes |
| prompts:read | Read tracking prompts and sentiment evidence | yes |
| prompts:update | Change tracking prompts | yes |
| articles:read | Read articles and brand context | yes |
| articles:write | Create or overwrite Content Studio articles | yes |
| articles:publish | Publish articles to your website | ask by name |
| images:write | Upload images to public storage | ask by name |
| brand:write | Edit your brand profile, competitors, audiences and notes | yes |
| integrations:write | Connect Google and set up tracking | yes |
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_websiteandsuggest_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.