Use your own AI

Tool reference

Every Starjay MCP tool at a glance, plus the conventions and errors they all share.

Starjay's MCP server, starjay, offers the 48 tools below. Your AI app lists them with their exact input schemas when it connects, so it always has the current inputs. The pages in this section explain each tool in plain terms, with examples and the errors you might see.

Conventions

siteId on every call. Every tool except list_sites needs siteId (string), the ID of the site to work on. Get it from list_sites or the editor's starter prompt. The tables on these pages leave siteId out, but the examples include it.
Paths are site-relative, such as src/pages/index.astro or brand/tokens.ts.
Turns. Tools that change the site need an open turn: call start_turn first and end_turn when you're done. Read-only tools work at any time. See How agent work shows up in the editor.
Results are JSON text. Some tools also return images (screenshots, image previews), which your AI app shows or reads directly.
Confirmation. publish, and set_publish_state with status deleted, need the user's explicit approval. Your AI asks you, then calls again with _confirmed: true.

All tools

Tool	Group	Needs an open turn
`list_sites`	sites and turns	No
`get_session_state`	sites and turns	No
`start_turn`	sites and turns	Opens one
`end_turn`	sites and turns	Must hold one
`cancel_turn`	sites and turns	No
`get_recent_changes`	sites and turns	No
`get_editor_focus`	sites and turns	No
`list_pages`	reading your site	No
`get_site_structure`	reading your site	No
`inspect_page`	reading your site	No
`list_components`	reading your site	No
`inspect_component`	reading your site	No
`list_files`	reading your site	No
`read_file`	reading your site	No
`search_files`	reading your site	No
`get_tokens`	reading your site	No
`get_brand_guide`	reading your site	No
`list_backups`	reading your site	No
`write_file`	editing	Yes
`patch_file`	editing	Yes
`modify_layout`	editing	Yes
`modify_tokens`	editing	Yes
`modify_element_defaults`	editing	Yes
`set_brand_guide`	editing	Yes
`list_items`	CMS	No
`modify_collection`	CMS	Yes
`modify_items`	CMS	Yes
`browse_assets`	images	No
`view_asset`	images	No
`import_asset`	images	Yes
`request_asset_upload`	images	Yes
`modify_asset`	images	Yes
`assets_usage`	images	No
`assets_apply_alt`	images	Yes
`list_forms`	forms, SEO and redirects	No
`modify_form`	forms, SEO and redirects	Yes
`seo_list`	forms, SEO and redirects	No
`seo_get_page`	forms, SEO and redirects	No
`seo_set_page`	forms, SEO and redirects	Yes
`seo_set_defaults`	forms, SEO and redirects	Yes
`redirects_list`	forms, SEO and redirects	No
`redirects_modify`	forms, SEO and redirects	Yes
`set_publish_state`	publishing	Yes
`publish`	publishing	No; refused during a session
`get_publish_status`	publishing	No
`get_preview`	preview, references and feedback	No
`fetch_reference`	preview, references and feedback	No
`send_feedback`	preview, references and feedback	No

Errors any tool can return

When Starjay refuses a call, the result is marked as an error and its JSON has an error value and usually a message. These can come from any tool:

You see	What it means	What to do
`site_required`	The call didn't include `siteId`.	Call `list_sites`, then pass the site's ID.
`forbidden`: "You do not have access to this site"	The signed-in account isn't a member of the workspace that owns the site.	Check the site ID, or ask the workspace owner to invite you.
`site_archived`: "This project is archived. Restore it from the dashboard to use it again."	The site is archived.	Restore it from the dashboard. Restoring needs Pro.
`editor_unavailable`: "The editor for this site is not running. Ask the user to open … then retry."	The site's editor isn't running, so the tool can't reach the site.	Open the site in the editor (the message gives the link), wait for it to load, then retry.
`not_lock_holder`	A change was attempted without an open turn, or the turn lapsed after about five minutes without calls.	Call `start_turn`, then retry.
`lock_lost`	The user clicked Take back control, or the turn expired and was reopened by someone else.	Call `start_turn` to resume, then retry.
`site_publishing`: "The site is publishing. Editing is paused until it finishes."	A publish is running.	Wait, check with `get_publish_status`, then retry.
`cancelled`	The turn was cancelled while this call was running.	Stop. Ask the user before starting again.
`confirmation_required`	The action needs the user's approval.	Ask the user. If they say yes, call again with `_confirmed: true`.
`insufficient_credits`	The workspace doesn't have enough credits for this action. The result shows `balance_credits`.	Ask the user to buy more credits or wait for the next refill.
`spend_authorization_unavailable`	Starjay couldn't check credits just now.	Retry in a moment.
"Tool … failed: …" (`dispatch_failed`)	Something went wrong while running the tool. The message has details.	Retry once. If it keeps failing, report it with `send_feedback`.

If your AI app says it's signed out or asks you to authenticate again, sign in again from the app's MCP settings. See Troubleshooting your own AI.