Integrations
MCP tools
Run Ulika as a local MCP server so any coding agent can connect sites, scan content and edit site code. Every tool with its inputs and outputs.
Last updated
ulika mcp runs the Ulika CLI as a Model Context Protocol (MCP) server on your own computer. Any MCP-compatible coding agent can then connect sites to Ulika, preview what Ulika would manage, and customise your site's source code, with structured results instead of terminal text. In your project's settings, under Integrations, it appears as Model Context Protocol: "Lets any MCP-compatible coding agent connect sites and edit content through the Ulika CLI."
You do not need MCP to let an agent connect a site: an agent with a terminal can simply run ulika connect. MCP adds structured results and a safe, scoped way to edit code. For the approval flow, limits and guard rails shared by both, read Connect with an AI agent.
Add it to your agent#
Run this server as a stdio MCP server: command npx, arguments -y <tarball> mcp. The tarball is served by Ulika, for example:
npx -y https://ulika.co/cli/ulika-cli-0.7.1.tgz mcpThe Set up panel#
You do not have to remember any of this. In a project, open Settings, then Integrations, and click Set up on Model Context Protocol (under Protocols). The panel opens with the exact text for your Ulika address, each with a copy button:
An introduction: "Ulika runs as a local MCP server over stdio. Register it once in your agent, then ask it to connect your site. It needs Node 20 or newer."
Claude Code: the
claude mcp addcommand (Copy the Claude Code command).Codex: the
codex installcommand (Copy the Codex setup command).Cursor and other MCP clients: "Add this to the client's MCP config (for Cursor,
~/.cursor/mcp.json)", followed by a JSON block (Copy the MCP JSON config):
{
"mcpServers": {
"ulika": {
"command": "npx",
"args": [
"-y",
"https://ulika.co/cli/ulika-cli-0.7.1.tgz",
"mcp"
]
}
}
}Run the server directly: the plain
npxcommand (Copy the MCP server command).Tools the server exposes: the nine tools below, each with a one-line summary, and "(read-only)" on the ones that cannot change anything.
The version in the address follows the CLI version your Ulika serves, so copy it from the panel rather than from this page.
The panel ends with a status line. If an agent used your workspace recently, it reads "An agent last used your workspace 2 hours ago. Ulika cannot see whether MCP is installed on a machine, so this is not shown as connected." Otherwise: "Ulika cannot see whether MCP is installed on a machine, so it stays on Set up until you use it." The row never shows Connected, because the server runs on your computer and Ulika cannot see it.
The same Claude Code command also appears under Want to change the code? on the read-only Website code page.
Agent-specific guides: Claude Code (claude mcp add) and Codex (ulika codex install).
Optional environment variables for the server:
| Variable | Effect |
|---|---|
ULIKA_TOKEN | A workspace token (starts with ovl_wt_). Lets connect_site run with no browser step. |
ULIKA_SERVER | Point the server at a different Ulika instance. Default https://ulika.co. |
Two ways to connect, and why there are two#
connect_siteis for the case where the agent is already inside the website's own checkout. It reads the project, scans it, and creates it. It has no required arguments. It never starts a browser approval, because an agent cannot approve a code and would wait forever. If this computer is not authorised it fails with an instruction: setULIKA_TOKEN, or ask the user to runulika loginonce.connect_sitesis for everything else: sites whose code is not on this computer, several sites at once, or no checkout at all. It uses Ulika's GitHub App and a one-time approval link. This is the one agents should prefer when they only know the site's address. It never blocks: it returns the approval link at once and keeps polling in the background, then submits the batch by itself the moment you approve.
The tools#
All nine tools are listed below (the Set up panel lists the same nine: connect_site, connect_sites, batch_status, approval_status, scan_site, connection_status, list_code_files, read_code_file and write_code_file; the read-only ones are batch_status, approval_status, scan_site, connection_status, list_code_files and read_code_file). Every argument is optional unless marked required. Results arrive both as text and as structured content. A failing tool returns an error result with a plain message; it never crashes the server.
Connect and inspect#
| Tool | Purpose | Inputs | Key outputs |
|---|---|---|---|
connect_site | Import a local website project (or resolve a Vercel domain) and return its Ulika URL. Installs a connector pull request and verifies the preview by default. Re-running refreshes the project instead of duplicating it. | dir (project root, default the current folder), url (deployed address), importOnly (skip installation), activate (merge the verified connector and verify production; only with the user's authorisation), scope (Vercel team), remoteSource (resolve url through Vercel even inside a project), server, dryRun (scan and report only) | connected, imported, installation, outcome (created or refreshed), projectId, projectName, projectUrl, editorUrl, approved, needsReview, summary, siteUrl, configFile, nextStep. With dryRun: dryRun, projectName, project, summary, existingProjectId, up to 25 fields, warnings. When the code is not on this machine: handoff and a url to finish in the browser. |
scan_site | Preview the content Ulika would manage: headlines, copy, images, links and SEO metadata. Reads files on this machine only; no network and no authorisation. | dir, limit (1 to 100, default 25) | scannedAt, project, summary, routes, filesScanned, filesSkipped, durationMs, extractor, warnings, fields (each with path, label, kind, type, value, source as file:line, component, route, section, confidence), note |
connection_status | Report whether this project is connected, and to which Ulika project, by reading ulika.config.json. | dir | connected (true only when production is verified), imported, installation, dir, config; or connected: false with reason (missing, unreadable or malformed) and note |
Connect many sites#
| Tool | Purpose | Inputs | Key outputs |
|---|---|---|---|
connect_sites | Connect one or many deployed websites in one batch with one human approval. | urls (array of addresses), repos (array of owner/name), all (every site in the repositories Ulika can see; do not combine with the other two), autoMerge (merge once the host's build passes; off by default, so each site waits for one Activate link), reviewFirst (the default, accepted and ignored), confirm (only with all: the user saw the list and agreed), server | When approval is needed: batchId: null, approval (url, code, expiresAt) and a nextStep. When already approved: batchId, resumed, sites, nextStep. For Ulika's own address or repository: refused: true, reason: "this-is-ulika", message, nextStep. |
approval_status | Whether the user has approved the link connect_sites returned. | server | status: pending (wait about 15 seconds and ask again), approved (with batchId once the batch started), denied, expired, failed, or none (nothing is waiting); plus approval, error, note, nextStep |
batch_status | Progress of a batch. Call about every 30 seconds while it is running. | batchId (required), after (the cursor from the previous call, to receive only new events), server | status: running, confirmation_required or done; summary, sites, events, cursor, nextStep. For confirmation_required: the list of sites (site, repo, siteUrl). For done: report with headline (N live · M need your attention · K failed), live, attention, failed, pending, summary and exitCode. |
The sequence an agent follows with connect_sites:
Call
connect_siteswith the addresses, repositories orall. If it returnsapproval, tell you exactly once: "Open <url> and approve code <code>. That is the only approval needed."Call
approval_statusabout every 15 seconds untilapproved.Call
batch_statuswith thebatchIduntildone, passing the previouscursorasafter.With
all,batch_statusfirst returnsconfirmation_required. The agent must show you the list, and only if you agree callconnect_sitesagain withallandconfirmset to true. Nothing is written before that.Present the
report: the headline, each live site with itseditorUrl, each attention item with its single next action (action.labelandaction.url), then failures. If a site waits for activation, the agent gives you the one Ulika link and keeps callingbatch_statusfor up to 15 minutes until it is live.
Code tools#
Three tools let an agent customise your website's code on your computer. They are for when you ask for code changes, not for content.
| Tool | Purpose | Inputs | Key outputs |
|---|---|---|---|
list_code_files | List source files the agent may customise. Read only. | dir, limit (1 to 300, default 200) | root, files (each with path, bytes, sha256), truncated |
read_code_file | Read one source file with its revision hash. Read it before proposing a change. Read only. | dir, path (required, repository-relative with forward slashes) | path, content, bytes, sha256 |
write_code_file | Save a changed file to the local source. | dir, path, content (the complete new file), expectedSha256 (the hash from read_code_file); all three but dir required | path, bytes, sha256, changed, saved: true, published: false |
The rules these tools enforce:
Read first, then write.
write_code_filerefuses unless the file still matches the hash you read, so it can never overwrite a change made in the meantime. The error is "The file changed since it was read. Read the latest version before editing again."Local draft only. Saving writes the file in your working tree. It does not commit, deploy, publish or change content in the visual editor. Review the change and use your normal Git and publish flow.
Only website source. Allowed extensions:
.astro,.cjs,.css,.html,.js,.jsx,.mjs,.scss,.ts,.tsx,.vue,.svelte. Files up to 400 KB, text only.Blocked. Hidden files and folders,
.envfiles,package.jsonand lock files (package-lock.json,pnpm-lock.yaml,yarn.lock,bun.lock,bun.lockb),ulika.config.json, links and folders instead of regular files, and generated or dependency folders (node_modules,.git,.next,dist,build,out,coverage,.turbo,.vercel,.cache).Confined to where the server started. Code tools only work inside the folder the MCP server was launched from. Launch it from the repository you want customised; a different
diris refused with "Code tools are limited to the project directory where the Ulika MCP server started."
What the server sends and keeps#
Scanning and code editing stay on your computer.
scan_sitesends nothing anywhere.connect_siteandconnect_sitestalk to Ulika. They send the derived content manifest (paths, sample values, file names and line numbers), never your source code.The agent token created by an approval is stored in
~/.ulika/config.json, as described in Connect with the CLI.
Protocol details#
The server speaks JSON-RPC 2.0 as one JSON message per line on standard input and output; diagnostics go to standard error. It understands MCP protocol versions 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05. It advertises tools only. It shuts down when the agent closes its input.
Was this page helpful?