# MCP server reference

URL: https://docs.xodia.ai/reference/mcp
Last updated: 2026-10-22

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

_Picture: Xodia's New project dialog on its first step, with Connect your AI opened under Start fresh and Import from GitHub and 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._

## Endpoint and sign-in

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

Endpoint:

```
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` |
| Discovery | `/.well-known/oauth-protected-resource` and `/.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. |
| Plans | Every plan, the free one too. |

Every path is on https://app.xodia.ai. Disconnect a client at any time under Settings, AI agent, Connected apps, and its access ends.

## Tools

26 tools in 11 groups, with their names as your client lists them. Read only tools change nothing; for the ones marked destructive, clients that follow MCP's hints ask you first.

### Projects

| Tool | What it does |
| --- | --- |
| `list_projects` Read only | Lists your workspace's website projects and when each was last opened. |
| `create_project` | Starts a new website from one of five starters: the Xodia template, Next.js, Astro, a React Router app or HTML on Vite, all on Tailwind v4. |

### Workspace and preview

| Tool | What it does |
| --- | --- |
| `open_workspace` | Starts the project's live preview and shares its Xodia link. |
| `get_project` Read only | Reads the site's framework, styling, CMS, host, editing tier, branch and unsaved changes. |

### Files

| Tool | What it does |
| --- | --- |
| `list_files` Read only | Lists the project's files with their sizes. |
| `read_file` Read only | Reads a file, with line numbers. |
| `write_file` | Creates or replaces a file. |
| `edit_file` | Changes part of a file by exact replacement, so edits stay small and safe. |
| `search_files` Read only | Searches the code for text or a pattern. |
| `delete_file` Destructive | Deletes a file or folder. |
| `move_file` | Moves or renames a file or folder. |

### Checks and logs

| Tool | What it does |
| --- | --- |
| `run_check` Read only | Runs a typecheck, a production build or a design check (design tells, low contrast, over-long lines) and reports every finding. |
| `get_logs` Read only | Reads the dev server log: compile errors, warnings and reloads. |

### Selection

| Tool | What it does |
| --- | --- |
| `get_selection` Read only | Gets the element you selected in Xodia, with its place in the source. |

### Checkpoints

| Tool | What it does |
| --- | --- |
| `save_checkpoint` | Saves the unsaved changes as a restore point, when you ask it to. |
| `list_checkpoints` Read only | Lists restore points, newest first. |
| `restore_checkpoint` Destructive | Takes the site back to an earlier restore point without losing current work. |

### Requests from Xodia

| Tool | What it does |
| --- | --- |
| `get_next_request` | Waits for the next change you ask for in Xodia and picks it up. |
| `reply_to_request` | Posts progress and the result back to you in Xodia. |
| `get_request` Read only | Checks a request's status, so cancelled work is dropped. |

### Skills

| Tool | What it does |
| --- | --- |
| `get_skill` Read only | Loads one of Xodia's skills for the work at hand. |

### Deploys

| Tool | What it does |
| --- | --- |
| `deploy_status` Read only | Shows the latest deploy on your host: state, address and log link. |
| `deploy_logs` Read only | Reads a failed build's log so your AI can fix it. |

### SEO and speed

| Tool | What it does |
| --- | --- |
| `run_seo_test` | Tests a live page with Google PageSpeed Insights: scores, Core Web Vitals and failed checks. |
| `get_seo_report` Read only | Reads the latest PageSpeed result without using a test. |

### Screenshots

| Tool | What it does |
| --- | --- |
| `take_screenshot` Read only | Captures the live preview in a real browser, at desktop or phone size, with console errors. |

## Prompts

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.

| Prompt | What it does |
| --- | --- |
| `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 |
| `polish [page, section or component]` | Give a Xodia page or component a finishing pass on the small design details |
| `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 |

## Request kinds

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.

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

## Errors

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.

| Field | What it holds |
| --- | --- |
| `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. |
| `hint`optional | What to do next, written for your AI: retry, pick another project, ask you to upgrade or publish first. |
| `action`optional | What you can do about it in Xodia, such as upgrading or signing in again. |
| `details`optional | Extra facts about the failure, such as the limit that was reached. |
| `retryable`optional | Present and true when the same call may work if tried again. |

For example, what reply_to_request returns when another app has already taken the request:

Tool result:

```json
{
  "error": {
    "code": "request_claimed",
    "message": "Another agent has taken over this request.",
    "hint": "Stop working on it and call get_next_request."
  }
}
```

### Actions

When an error carries an action, it names what can fix it:

| Action | What to do |
| --- | --- |
| `retry` | Try the same call again, after Retry-After seconds when the response gives them. |
| `sign_in` | The session or token ended: sign in to Xodia again. |
| `open_preview` | Open the project's workspace first (open_workspace) so its preview runs. |
| `restart_preview` | Restart the preview, then try again. |
| `connect_cloudflare` | The workspace's own Cloudflare account needs connecting in Previews. |
| `reconnect_cloudflare` | Cloudflare stopped accepting Xodia's access: connect it again. |
| `upgrade_workers_paid` | The Cloudflare account needs the Workers Paid plan for previews. |
| `install_runtime` | Install Xodia's runtime on the workspace's own Cloudflare. |
| `update_runtime` | Update Xodia's runtime on the workspace's own Cloudflare. |
| `connect_agent` | Connect an AI app to the workspace. |
| `upgrade_plan` | A plan limit was reached: ask the user to upgrade in Billing & usage. |
| `start_helper` | The Xodia helper isn't running: start it with the command from Xodia. |
| `add_card` | The workspace needs a verified card first. |
| `verify_email` | The owner's email address isn't verified yet. |
| `reconnect_insights` | An analytics source's access was rejected: connect it again in Insights. |
| `enable_analytics` | Analytics are off at the provider: turn them on there. |
| `ask_agent` | Xodia can't make this change visually: send it to the user's AI. |
| `reconnect_cms` | The CMS no longer accepts the saved token: paste a new one in the Content tab. |
| `top_up` | Built-in AI tokens are used up: a top-up pack in Billing & usage gets past the limit. |
| `wait` | Nothing to buy or change: try again at details.resetsAt. |
| `contact_owner` | The caller can't fix it: ask a workspace owner. |

### Rate limits and maintenance

A client that makes more calls than Xodia allows in a minute gets the error `rate_limited` with the action `retry`, and its details say how many seconds to wait. While Xodia is being updated, calls answer `maintenance`; try again after the time it gives.

> **Note:** Tools edit files as unsaved changes and save restore points only when asked. Saving to the live branch of a site imported from GitHub is refused, and publishing stays a button in Xodia. Setup for each app is in [Ways to connect your AI](https://docs.xodia.ai/ai).