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. 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/mcpUsed by a client that cannot read a site folder on your computer. It writes a Birta draft file by file and publishes it on a separate publish request once the work is done; ask for the draft's own address when you want to look before it goes live.
Local connection
stdio · browser approval · draft first
npx -y @birta/cli mcpUsed 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 and publishes on a separate publish request once the work is done; ask for the draft's own address when you want to look before it goes live.
| 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, because 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, write_file, edit_file, replace_lines, move_file, delete_file (or upload the folders again with upload_draft, which replaces the draft whole) |
| 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.
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 published by its own separate call. An owner who asks to look first is handed the draft's address before that call and the publish waits for their word; the sequence is otherwise the same. 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
publish_version -> live URL + that version's own review address
GET version address -> that version, for whoever holds the address (the default)
list_version_comments -> the remarks left on that page
create_version -> write_file -> publish_version -> next live versionLocal: 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.
publish_version -> live URL + that version's own review address
list_version_comments -> the remarks left on that page
upload_draft (next round) -> draft version 2 -> publish_versionCompatibility and limits
- The served site must contain a root
index.html. - Browser HTML, CSS, JavaScript, images, and supported static assets work. No server side, no database, no server-side authentication, no always-on processes.
- A single-page app can be published. Its in-app navigation has to run through
#: with regular paths, opening or refreshing any path other than the root returns “page not found”. - 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