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. Open Computers in the dashboard, start the plan and create a Computers key. It is a separate credential: it only works on the MCP server and /api/v1/computers, and every other Maritime endpoint rejects it. The reverse is also true: manage keys and dashboard sessions cannot reach Computers.
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 on the Computers page. 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.

What counts as an invocation

The plan is priced in invocations. An invocation is one session on one computer. 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. Actions inside an open session are never counted again and never blocked by quota.
• 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 with no new charge. 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.
• A session that reaches the plan's wall cap (60 minutes) closes; the computer stays awake and the next action opens a new session, which is one more invocation.
• Waking a computer, watching it through a viewer link, and takeover never open a session. They are free.
• Quota is checked only when a new session would open: 402 quota_exceeded when the period's included invocations are used up, 429 concurrency when the plan's concurrent sessions are all in use.

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

Start it on the Computers page. The same page shows invocations used this period, the period end, and the Stripe portal.

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.
• A leaked Computers key can burn invocations and nothing else: it reaches no other Maritime endpoint.