Skip to content
Start free
Every plan

Xodia MCP server reference

Xodia is a remote MCP server. Any MCP client connects over Streamable HTTP, signs in with OAuth and gets 26 tools and 8 prompts for working on websites in Xodia. This page lists every one, with how sign-in works and what a failed call returns.

Start freeConnect your AI

Free plan. 14-day Pro trial. No charge unless you choose a plan.

Xodia's New project dialog on its first step, Connect your AI agent, with the Other tab open: add a remote MCP server with Streamable HTTP, OAuth sign-in and the Xodia MCP URL, then sign in and ask.

Connection

Endpoint and sign-in

Point your client at one address. It discovers the sign-in from the server's metadata, registers itself and asks you to approve access in the browser.

Endpoint
MCP server URL
https://app.xodia.ai/mcp
Transport

Streamable HTTP. No local process to install or run.

Sign-in

OAuth 2.1 with the authorization code flow and PKCE (S256). Clients register themselves with dynamic client registration, so there is no client ID or key to copy.

  • Registration/oauth/register
  • Authorization/oauth/authorize
  • Token/oauth/token

Every path is on https://app.xodia.ai.

Discovery

Clients find the sign-in from the server's metadata:

  • /.well-known/oauth-protected-resource
  • /.well-known/oauth-authorization-server
Scopes

xodia and offline_access. The second lets your client stay signed in without asking again.

Tokens

Access tokens last 1 hour; refresh tokens 60 days. Disconnect an app in Xodia at any time to end its access.

Plans

Every plan, the free one too.

Tools

26 tools, in 11 groups

Tool names as your client lists them, with what each one does. Read only tools change nothing; for the ones marked destructive, clients that follow MCP's hints ask you first.

  • Projects

    • list_projectsRead onlyLists your workspace's website projects and when each was last opened.
    • create_projectStarts a new website from Xodia's starter template.

  • Workspace and preview

    • open_workspaceStarts the project's live preview and shares its Xodia link.
    • get_projectRead onlyReads the site's framework, styling, CMS, host, editing tier, branch and unsaved changes.

  • Files

    • list_filesRead onlyLists the project's files with their sizes.
    • read_fileRead onlyReads a file, with line numbers.
    • write_fileCreates or replaces a file.
    • edit_fileChanges part of a file by exact replacement, so edits stay small and safe.
    • search_filesRead onlySearches the code for text or a pattern.
    • delete_fileDestructiveDeletes a file or folder.
    • move_fileMoves or renames a file or folder.

  • Checks and logs

    • run_checkRead onlyRuns a typecheck or a production build and reports every error.
    • get_logsRead onlyReads the dev server log: compile errors, warnings and reloads.

  • Selection

    • get_selectionRead onlyGets the element you selected in Xodia, with its place in the source.

  • Checkpoints

    • save_checkpointSaves the unsaved changes as a restore point, when you ask it to.
    • list_checkpointsRead onlyLists restore points, newest first.
    • restore_checkpointDestructiveTakes the site back to an earlier restore point without losing current work.

  • Requests from Xodia

    • get_next_requestWaits for the next change you ask for in Xodia and picks it up.
    • reply_to_requestPosts progress and the result back to you in Xodia.
    • get_requestRead onlyChecks a request's status, so cancelled work is dropped.

  • Skills

    • get_skillRead onlyLoads one of Xodia's skills for the work at hand.

  • Deploys

    • deploy_statusRead onlyShows the latest deploy on your host: state, address and log link.
    • deploy_logsRead onlyReads a failed build's log so your AI can fix it.

  • SEO and speed

    • run_seo_testTests a live page with Google PageSpeed Insights: scores, Core Web Vitals and failed checks.
    • get_seo_reportRead onlyReads the latest PageSpeed result without using a test.

  • Screenshots

    • take_screenshotRead onlyCaptures the live preview in a real browser, at desktop or phone size, with console errors.

Prompts

8 prompts to start from

Clients that support MCP prompts list these, each with an argument for what you want. In Claude Code, Xodia's plugin turns them into /xodia commands.

  • build <what to build>Build or redesign a Xodia website from a description
  • work [project name]Listen for change requests from Xodia and work through them
  • animate <what should move, and when>Add interactions and animation to a Xodia site: hover, reveals, scroll effects, page transitions
  • content <what to add or change>Add or change CMS content and collections on a Xodia site: posts, projects, team, drafts
  • fix [what looks wrong]Find and fix what's broken in a Xodia preview
  • review [project name]Review a Xodia project's unsaved changes before saving
  • seo [page or goal]Check and improve a Xodia site's SEO and AI search readiness
  • speed [page]Make a Xodia site load faster

Requests

Request kinds and the skills they load

Requests sent from Xodia's ask box arrive through get_next_request with a kind. Each kind names the skills to follow; your client loads them with get_skill.

Stack pack skills for the site's framework, styling, CMS and host load the same way; CMS and host packs come with Starter, Pro and Agency.

  • Auto (auto)Let the agent decide. Skills: Request router, Guardrails.
  • Content (content)Wording, images, links. Skills: Content changes, CMS content, Page settings, Image optimiser, Safe edits, Verify, Site memory (AGENTS.md).
  • Design (design)Look and layout. Skills: Design system, Dark mode and themes, Extract design tokens, Accessibility, Interactions, Navigation, Fonts, favicon and 404, Image optimiser, Safe edits, Verify, Site memory (AGENTS.md).
  • Page (page)New or restructured pages. Skills: Plan and confirm, New page, New section, Components, Navigation, Forms, Languages and regions, Fonts, favicon and 404, Draft pages, Page settings, Redirects and retired pages, Design system, Image optimiser, SEO basics, Safe edits, Verify, Site memory (AGENTS.md).
  • Fix (fix)Something is broken. Skills: Visual fixer, Environment and hosts, Analytics and scripts, Image optimiser, Safe edits, Verify, Site memory (AGENTS.md).
  • Ask (question)A question, no changes. Skills: Request router.

Errors

Errors come back as tool results, with a hint

A failed call doesn't break the session. It returns a normal tool result marked as an error, with a JSON error object your AI can read and act on.

code
A short machine name for what went wrong, such as a plan limit or a file that isn't there.
message
What went wrong, in plain words.
hintoptional
What to do next, written for your AI: retry, pick another project, ask you to upgrade or publish first.
actionoptional
What you can do about it in Xodia, such as upgrading or signing in again.
detailsoptional
Extra facts about the failure, such as the limit that was reached.
retryableoptional
Present and true when the same call may work if tried again.
What reply_to_request returns when another app has already taken the request:
{
  "error": {
    "code": "request_claimed",
    "message": "Another agent has taken over this request.",
    "hint": "Stop working on it and call get_next_request."
  }
}

Questions

MCP questions

Do I need an API key?

No. Clients sign in with OAuth and register themselves, so there is no key or client ID to create or paste.

Does my client need to support OAuth?

Yes. Xodia accepts only signed-in clients, and signing in goes through OAuth in your browser.

Which clients have setup steps?

Xodia's own setup guide covers Claude Code, the Claude app, Cursor, Codex and VS Code. Any other client that speaks Streamable HTTP with OAuth connects the same way.

Can my client publish the site?

No. Tools edit files as unsaved changes and save restore points when you ask. Saving to the live branch of a site imported from GitHub is protected, and you publish from Xodia yourself.

Keep exploring

Other ways to connect

Connect your MCP client and start editing.

Start freeSee pricing