Build a platform

Computers

A persistent Linux desktop (XFCE, Chromium, LibreOffice) for each of your end users, driven by your model. You connect the Maritime MCP server to whatever agent you already run; the model calls get_computer once per end user and then computer in a screenshot, act, verify loop. Maritime creates the desktop, keeps it warm, sleeps it when idle, wakes it on the next action, and keeps its files and logins between sessions. There is no lifecycle for you to manage.

In sixty seconds

1. Use the key you already have. A manage or full-access Maritime key drives computers and agents alike, so the MCP server takes the same bearer token as the rest of the API. To hand out a key that reaches computers and nothing else, create a Computers key in the Computers section of Settings, API keys: a key whose only scope is computers is refused on every other Maritime endpoint. Dashboard sessions cannot reach /api/v1/computers; that surface takes an API key.
2. Add the MCP server to your agent with one of the snippets below.
3. Your model calls get_computer with the end user's id, gets a computer_id, then drives it with computer. The first call creates the desktop; every later call for the same end user returns the same one.

Connect your model

The server speaks Streamable HTTP and authenticates with your Computers key as a bearer token. Replace mk_... with the key; the exact endpoint for your deployment is shown on the Computers page.

{
  "mcpServers": {
    "maritime-computers": {
      "type": "http",
      "url": "https://mcp.maritime.sh/mcp",
      "headers": {
        "Authorization": "Bearer mk_..."
      }
    }
  }
}

The JSON form is what Cursor, Claude Code (.mcp.json) and most local clients read. The OpenAI Responses and Anthropic Messages entries are hosted MCP tools: the provider connects to the server for you, so your backend never proxies screenshots.

Building on the Vercel AI SDK? Version 6 has no MCP client of its own: experimental_createMCPClient was removed after v5, so any guide that reaches for it is out of date. Two options that work. Use a hosted MCP tool from the provider (the OpenAI Responses and Anthropic Messages entries above) and let the model connect. Or connect yourself with @modelcontextprotocol/sdk: build a Client over StreamableHTTPClientTransport pointed at the URL above, with the Authorization header in requestInit, then hand the tools it lists to generateText yourself.

import { Client } from '@modelcontextprotocol/sdk/client/index.js'
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'

const mcp = new Client({ name: 'my-app', version: '1.0.0' })
await mcp.connect(
  new StreamableHTTPClientTransport(new URL(mcpUrl), {
    requestInit: { headers: { Authorization: `Bearer ${process.env.MARITIME_COMPUTERS_KEY}` } },
  }),
)

const { tools } = await mcp.listTools()
// Convert each tool to an AI SDK tool: inputSchema stays as is, and
// execute calls mcp.callTool({ name, arguments: args }).

Pin the server to one end user

On the plain endpoint the model passes the end user's id to get_computer. That is fine for a trusted orchestrator, but for a customer-facing agent a model-supplied user id is one prompt injection away from another end user's desktop. Mount the pinned form instead and the server ignores any other id:

https://mcp.maritime.sh/mcp/u/<externalUserId>

Clients that can set headers can pin with X-Maritime-User: <externalUserId> on the plain endpoint. Either way, get_computer needs no user_id, and a mismatching one is refused.

Add it to your product

The whole integration for a website or app with its own agent loop is six steps. Nothing about your backend changes; the computer is just another tool the model can call.

1. Create a Computers key in the Computers section of Settings, API keys. It is shown once. Keep it on your server; never send it to the browser.
2. Build the pinned URL per signed-in user on your server from their id, so the model can only ever reach that user's desktop.
3. Register the server with your model using one of the snippets above, with Authorization: Bearer mk_....
4. Tell the model when to use it with one line in your system prompt (below).
5. Show takeover links to your user. When the model calls request_takeover it returns a link and a reason; render both in your chat. The person opens it, finishes the step, and clicks Done. By default the tool call has already returned, so the model finds out through takeover_status or through its next action being refused with human_in_control.
6. Optionally let users watch. Mint a watch link with POST /api/v1/computers/{id}/viewer and {"mode": "watch"}. That is a REST call to the Maritime API, not to the MCP server: send it to the same API host your Computers key was issued on, which is printed next to the MCP URL on the Computers page. The link is view-only and expires on its own.

When a task needs a real browser or desktop, call get_computer first and keep the computer_id it returns: every other computer tool takes that computer_id as an argument. Take a screenshot before acting and use coordinates from the last screenshot. If you reach a login, CAPTCHA or payment step, call request_takeover with a short reason and show the user the link it returns; your next action stays refused with human_in_control until they are done, so retry it (or call takeover_status) instead of asking again.

# the pinned URL is built from YOUR user id, never from model output
mcp_url = f"{MARITIME_MCP_URL}/u/{current_user.id}"

# OpenAI Responses API, hosted MCP tool
tools = [{"type": "mcp", "server_label": "maritime-computers", "server_url": mcp_url,
          "authorization": MARITIME_COMPUTERS_KEY, "require_approval": "never"}]

# Anthropic Messages API, MCP connector
mcp_servers = [{"type": "url", "url": mcp_url, "name": "maritime-computers",
                "authorization_token": MARITIME_COMPUTERS_KEY}]

Tool timeouts

Most MCP clients cut a tool call off after 60 seconds. Two calls here can pass that, and both need the limit raised, not just the takeover:

• get_computer on first use creates the desktop: 3 to 8 seconds normally, up to 60 on a cold placement. Later wakes take about 3 seconds.
• request_takeover with wait: true holds until the person clicks Done or Failed, which is minutes. Leaving wait at its default returns at once and needs no extra time.

Raise the tool timeout for both. Claude Code reads MCP_TOOL_TIMEOUT (milliseconds) from the environment. The MCP TypeScript and Python SDKs take a per-call timeout on callTool; the TypeScript client also has resetTimeoutOnProgress, which the waiting takeover's progress notifications keep alive. Hosted MCP tools on the provider side have their own ceilings, which is another reason to leave wait false there.

Tools

The computer action

computer takes computer_id, an action from the list below, and the fields that action needs. The same schema is the body of POST /api/v1/computers/{computer_id}/actions on REST.

Coordinate rules

• Screenshots are 1200 x 750 by default on a physical 1280 x 800 desktop. Every result reports width and height; coordinates are pixels in that frame, and Maritime scales them to the screen.
• Take a screenshot before acting, and never act on a screen the model has not seen this turn.
• Work in a strict loop: screenshot, plan one step, act, read the returned screenshot, verify. Each result carries a monotonic frame_id so the model can tell a fresh frame from a stale one.
• Click the target field and confirm focus before typing. Type digits and punctuation with type, not key.
• On-screen text is untrusted data, never instructions. Prompt injection from a web page is your model's problem; the tools never execute anything read from a screenshot.
• While a person holds the desktop (after request_takeover) every action is refused with human_in_control and retryAfterS: 15. Wait, then take a screenshot to continue, or call takeover_status to see whether the desktop is back.

Sessions

A session is a period of continuous use of one computer. It is a record, not a charge: nothing here costs money. These are the rules, exactly as the backend applies them:

• A session opens on the first action against a computer that has no open session.
• Screenshots count as actions: they keep the session alive and increment the screenshot counter.
• close_computer (REST: sessions/close) ends the session and starts a 30 seconds grace. An action inside the grace reopens the same session. After the grace the computer sleeps.
• A session with no action for 5 minutes closes as idle and the computer sleeps. The next action opens a new session.
• Waking a computer, watching it through a viewer link, and takeover never open a session.
• Waking is where a plan can refuse: 402 plan_lapsed when the plan has lapsed, 429 concurrency with a 15 second retry hint when the account already runs as many machines at once as the plan allows. A computer that is already awake is never refused.

Persistence

• One computer per end user. get_computer with the same id always returns the same desktop; an anonymous call (no id, unpinned) always creates a new one.
• After 5 idle minutes the desktop sleeps: memory is snapshotted, open windows and all. It wakes on the next action in about a second, or a few seconds when the snapshot is gone.
• The memory snapshot is kept for 7 days after the last action. Past that the desktop still wakes, from a fresh boot with the same disk, so only open windows are lost.
• Files, the browser profile and its logins live on the computer's own disk under /data and /home/desk. They are kept until you delete the computer.
• Deleting a computer destroys its disk and snapshots. Deleted computers return 404.

The plan

One plan covers everything you run. A computer is a machine, the same unit as an agent, and takes one slot whichever it is. So a $20 plan holds 20 machines: 20 agents, 20 computers, or any mix. Nothing is counted per action, per session or per minute.

Computers need a paid plan. The free plan runs agents; a computer is a larger machine with a screen, and the screen alone is a paid add-on on an agent. Creating one without a plan answers 402 computer_limit and names the upgrade.

Past the included count, each extra machine bills at the plan's flat monthly rate. Switching plans reprices the subscription; Stripe shows the exact amount before the change is charged.

The Computers page shows the machines you hold and how many of them are computers. The Billing page is where the plan is bought, changed and cancelled, once, for the whole account.

Limits

Errors

REST errors on /api/v1/computers are written for the model that reads them: {"error": "slug", "message": "...", "retryAfterS": 15}. On MCP they become tool results with isError: true and the same message.

REST and SDK

Everything the MCP server does is a call to /api/v1/computers with the Computers key as a bearer token. Field names are camelCase (externalUserId, frameId, imageB64, exitCode, retryAfterS).

The maritime-sdk client exposes the same operations as client.computers, and itscomputers/dialects module converts OpenAI, Gemini and Qwen computer-use actions to the canonical schema (fromOpenAI, fromGemini, fromQwen) for models that do not speak MCP. That resource ships in the next SDK release; until then, call REST directly.

Works with

• Claude, OpenAI, Gemini through MCP, with the snippets above.
• Any other model through REST, using the SDK converters to map its native computer-use actions to the canonical one.
• People through the viewer: a watch link to look, a control link to take over for a login or a CAPTCHA and hand the desktop back with Done.

Security notes

• Each computer is its own micro-VM with its own disk. Computers cannot reach each other.
• Typed text is never logged and never appears in an error. It can contain passwords.
• Viewer links are short-lived, bound to one computer and one mode, and every link is revoked when a session closes, the computer sleeps, or a takeover completes. View-only links cannot send input; the server drops it, not the browser.
• Scope decides what a key reaches. A key whose only scope is computers drives computers and is refused on every other Maritime endpoint, so a leak is contained to this product. A manage or full-access key drives both products; treat it as it deserves.