Product reference

Birta MCP reference

Birta lets a supported AI client build and publish a website through MCP. It does not host an MCP server for you. There are two connections — hosted for a client that cannot read your computer's files, local for one that can — and which one your client uses is settled by its own guide, not by you. This page documents both.

New to the protocol? Read the plain-English MCP explainer. This page is the exact Birta setup and behavior reference.

The two connections

Hosted connection

Streamable HTTP · browser OAuth · draft first

https://birta.dev/mcp

Used by a client that cannot read a site folder on your computer. It writes a Birta draft file by file, gives you the draft's own address to look at and mark up, and publishes only on a separate publish request.

Local connection

stdio · browser approval · draft first

npx -y @birta/cli mcp

Used by a client that works with files on your machine. Node.js 20 or newer is required. It uploads the project folder and the built-site folder into the Birta draft, gives you the draft's own address, and publishes only on a separate publish request.

Decision	Hosted	Local
Transport	Streamable HTTP	stdio
Authorization	OAuth in the browser	Approve the installation in the browser
File handoff	Client writes the draft file by file	Client names the source and served folders; the connection uploads them
Before publication	Draft at its own address, kept across rounds of edits	Draft at its own address, kept across rounds of edits
Publication	Explicit publish by draft version	Explicit publish by draft version

Verified client routes

These are the client surfaces currently documented by Birta. Follow the focused guide for current menu labels and config shape. A client not listed here is not automatically incompatible, but it is not verified by this reference.

Client	Connection	Guide
Claude Web	Hosted	Open guide
Claude Desktop	Hosted	Open guide
Claude Cowork	Hosted	Open guide
ChatGPT Web	Hosted, when the workspace exposes the required connection controls	Open guide
Claude Code	Local	Open guide
ChatGPT Desktop	Local	Open guide
Codex	Local	Open guide
Cursor	Local	Open guide

Tool reference

The two sets differ in exactly one thing. A hosted client edits the Birta draft file by file, because it has no local folder to hand over. A local client hands over whole folders instead, so it has no per-file editing — the files are changed on the machine and uploaded again. Everything else is the same set, including publishing the draft and throwing it away.

Capability	Hosted tools	Local tools
Projects	`list_projects, create_project, rename_project`	`list_projects, create_project, rename_project`
Versions and publication	`list_versions, create_version, publish_version, delete_version`	`list_versions, upload_draft, publish_version, delete_version`
Draft files	`list_files, read_file, write_file, edit_file, replace_lines, move_file, delete_file`	`list_files, read_file` (read-only, and over the version's stored sources; the draft's content is set by uploading the folders again)
Remarks on a version	`list_version_comments`	`list_version_comments`
Lead forms	`list_forms, get_form, create_form, update_form, delete_form`	`list_forms, get_form, create_form, update_form, delete_form`
Leads	`list_leads, get_lead`	`list_leads, get_lead`
Project settings	`project_settings, set_site_mark, set_version_access, share_project, revoke_access, connect_domain, verify_domain, disconnect_domain`	`project_settings, set_site_mark, set_version_access, share_project, revoke_access, connect_domain, verify_domain, disconnect_domain`
Recovery and measurement	`rollback, stats`	`rollback, stats`

The hosted surface currently negotiates 32 tools; the local surface negotiates 27. Neither surface exposes project deletion, lead deletion, a mark-read action, or writing into a remark thread. Taking someone off a project and disconnecting a domain answer the first call with what would happen and change nothing; they act on a repeat call that carries a confirmation.

Authorization behavior

Hosted: complete OAuth

An unauthenticated request receives a bearer challenge. A capable client discovers the protected-resource metadata, opens the browser authorization flow, and returns with its own access. There is no API key to paste into the client.

Local: approve, then retry

The first protected tool call returns a confirmation link and does not run the requested operation. Approve the installation in the browser, then call the tool again. The refused request is never queued for later execution.

What a session looks like

The call sequence each connection goes through, from the first refused request to a live site. Both end the same way: a draft the owner has looked at, published by its own separate call. These describe the Birta protocol flows—not every third-party client UI or workspace policy.

Hosted: authorization, then a draft written file by file

POST /mcp without a bearer token
-> Unauthorized; WWW-Authenticate points to protected-resource metadata

dynamic client registration -> HTTP 201
authorization redirect       -> HTTP 302
token exchange               -> HTTP 200
listTools                     -> 32 tools

create_project -> create_version -> write_file
GET draft address -> the draft, for whoever holds the address (the default)
list_version_comments -> the remarks left on that page
write_file (again, same draft) -> same number, same address
publish_version -> live URL

Local: approval, then a draft filled from folders

listTools -> 27 tools
list_projects
-> Authorization is required. The operation was not run.
   Open the returned link, approve access, then call this tool again.

resolve connection request -> HTTP 200, pending
approve installation       -> HTTP 200, approved
list_projects retry        -> success

create_project -> upload_draft({ dir, site_root, project })
-> Draft version 1, at its own address. Nothing is live.
list_version_comments -> the remarks left on that page
upload_draft (again) -> same number, same address, content replaced
publish_version -> live URL

Compatibility and limits

The served site must contain a root index.html.
Browser HTML, CSS, JavaScript, images, and supported static assets work. A project-owned server, database, authentication runtime, scheduled work, or private runtime secret does not.
A site published from separately built source must be updated through that source and build path. Hosted file tools cannot safely edit the generated output as if it were the source project.
Client support depends on its transport, OAuth, local-process, and workspace controls. Protocol support alone is not a promise that every MCP client works.
A rejected package is never stored: neither the draft nor the live site changes. Publishing is always a separate call on an existing draft, so nothing goes live as a side effect of an edit.

Troubleshooting

Hosted request says unauthorized

Let the client complete the browser authorization flow, then retry. If it never opens a flow, use one of the verified client guides rather than pasting a token manually.

Local request asks for approval

Open the returned confirmation link, approve the installation, and repeat the original tool call. Approval does not replay it.

Package validation fails

Confirm that the served folder—not merely the source folder—contains index.html at its root and that referenced assets remain inside the package. Every blocking problem is reported at once, and the draft is left exactly as it was.

The site did not change

Editing or uploading only changes the draft. The project address serves the last published version until publish_version is called on the draft.

The site needs server behavior

Stop the static publication path. Keep the project on a platform that runs the required server, database, authentication, jobs, or private secrets.

Connect the client you already use

Start with the exact guide for your client. It carries the current menu path and config, while this reference remains the source for Birta's hosted and local behavior.

Choose a client guide