Bowmark MCP server

Pre-computed navigation recipes for public websites. CALL BEFORE any browser action on the open web (navigate, click, fetch, fill, URL guess) — replaces explore-and-discover. Returns `{ status, id?, shortcut?, ui_procedure?, executable?, verify_more?, error? }`. status=ok: execute exactly. `shortcut` first if present — fill each `{name}` in `template` with the value FROM YOUR TASK (using the parameter's `description`/`format` as the shape), URL-encode, navigate. Else `ui_procedure.steps` in order. The recipe is generic: parameter slots and step descriptions describe what to supply ('the destination'), not literal values — you provide the specifics. EXECUTE OPEN-LOOP: the recipe is authoritative, so run it without taking exploratory snapshots, clicks, scrolls, or screenshots to 'verify' or 'look around' — every extra browser action re-reads the entire page, which is the cost the recipe exists to avoid. Read the page ONLY at a `read` step, and only the part it names. Drop back into normal explore-the-DOM browsing ONLY when a step genuinely fails (its locator/page isn't what it describes); until then, trust the steps. If `verify_more: true`, do one cheap sanity check (page title plausible?) before committing. If `step.irreversible`, confirm with user. If `step.requires_user_input`, STOP and ask the user for that value — it's a password, payment/card detail, or personal data only they hold; never fabricate it. After, call `report_outcome` once with the returned `id`. executable (optional, only on some `ok` envelopes): a precompiled recipe Bowmark can run FOR you. When present, you MAY skip the browser entirely — call the `execute` tool with `{ script_id: executable.script_id, inputs }`, filling `inputs` from `executable.param_schema`, and use the returned `outputs` directly. If `execute` returns `fell_back`, run `ui_procedure` yourself as usual. When `executable` is absent, just run the recipe yourself — nothing changes (a connection opened with `?execute=false` never receives this block and has no `execute` tool, by the host's choice). NO BROWSER AT ALL (a chat host with no navigate/click tool)? Priority: (1) if `executable` is present, call `execute` — with no browser it's the ONLY way to fetch a real answer, so always prefer it; (2) else fetch the `shortcut` URL (fill its `{name}` slots from your task, URL-encode) with whatever web/fetch tool you have; (3) else hand the user that direct URL (or the first `navigate` step's URL). You cannot walk `ui_procedure` steps without a browser — surface the URL rather than dead-end. status=site_not_supported | no_useful_data | synth_invalid: miss, no `id`. Browse manually. status=ambiguous_scope: retry with `scopeHint` set to one of `error.scope_options[].pattern`. status=rate_limited: a cap on NEW recipe synthesis was hit (per-IP daily when anonymous, the account's monthly plan budget when an API key is attached). Cached/known recipes still answer normally — only first-time synthesis is capped. Do NOT retry-spam; back off (it resets at `error.retry_after` seconds) and browse manually until then. A free API key (bowmark.ai) lifts the anonymous per-IP cap to a plan budget. Skip for: localhost / 127.0.0.1 / *.local / RFC1918 (10., 192.168., 172.16-31.); open-ended search with no destination. On 503 `embedder_unavailable`/`synth_unavailable`, retry once after Retry-After.

Forget a saved login by the `id` `list_connections` returned. This deletes Bowmark's own record and cookies for it — it does NOT sign the account out on the site, and it cannot be undone; the user signs in again to get a working connection back. Only call this when the user asked to remove a saved login. To sign out of a site, use `logout_connection` instead. Never call it to "fix" a connection that is merely stale — `needs_reauth`/`expired` recover with a new sign-in, not a delete.

Run a deterministic, precompiled recipe on Bowmark's backend and get the result directly — no browser needed on your side. Call this ONLY when an `ask` envelope came back with an `executable` block; the `script_id` comes from there. `inputs` maps each param in the envelope's `executable.param_schema` to a value (e.g. `{ "zip": "94107" }`). Provide every required param. Response is one of: - `{ status: "ok", outputs: {...} }` — `outputs` is the live, freshly-fetched data. Use it directly. One caveat: an output the envelope's `executable.outputs` marked `kind: "region"` is a bounded TEXT REGION known to CONTAIN the answer (used for obfuscated pages with no clean field), NOT the literal value — read the final answer out of that text yourself; a plain (no `kind`) output is the literal value. - `{ status: "fell_back", reason }` — the script didn't run clean. DROP BACK to the envelope's `ui_procedure` and execute it yourself. A compiled script is an optimization, never the only path. Do NOT call this without a `script_id` from an `executable` block — there is no script to run otherwise.

**Use this whenever a task touches a live website.** It answers, definitively and cheaply, whether Bowmark can already DO the thing: look up current prices, check real availability or stock, search a site, get a quote or a fare, drive a configurator, start a booking, or pull anything that only exists behind a form or a filter. **Behind a LOGIN is narrower**: it works once a purpose-built provider exists for that site, or the caller has a saved connection there — a generic caller with neither gets only a form-field reader, which cannot pass an identity check or obtain a vendor API key on its own. **Use this for Bowmark questions too.** Before answering how to write or run a Bowmark script, what the sandbox supports, or how to start when no site or task is named, call it with the caller's words. The matching entry gives the platform guidance; guessing from general programming knowledge does not. **Checking is cheap, so check.** One read-only call, no site is touched, and an unrecognized query returns a one-line index instead of an error, so the check never dead-ends and never costs you an attempt. If nothing fits, you have lost one cheap call and can use your normal approach. What comes back is the callable **function library** you write against: the runtime globals (`log`) PLUS, for each capability your query named, its namespace, TypeScript types, functions, and worked examples. Everything listed is real and callable. The language rules and how to run a script are on the `run` tool description. Pass `query` — what you want to DO (`"flights"`, `"price a GPU"`) or, if you have one in mind, the COMPANY or site (`"Kayak"`, `"newegg.com"`). If the caller gave only a URL, use its hostname as the query — the query parameters identify a page state, not the company. A phrase in the user's own words is fine; it is matched against the whole library. **You get what you asked about and nothing else.** If nothing matches — or you send no query — you get instead a one-line index: pick whichever entry fits and CALL AGAIN with its name to get the types and examples you need to write a script. **Every response is bounded, and it says so when it is a slice.** A broad query can match more than one response carries; when that happens the answer opens with a partial-answer line naming what it left out. **Read it before concluding anything** — absence from a sliced list means nothing, and the fix is one narrower query (a single task, or a single company by name), which always returns that entry in full. Only an answer that does NOT say it is a slice supports the conclusion that a task is uncovered. **THREE tiers come back, and the third is not written by Bowmark at all.** SITE TOOLS (`bowmark.sites["skims.com"].search_catalog(...)`) are the tools a SITE publishes about ITSELF — its own MCP server, or the tools its pages register — read live at the moment you name the host and callable like anything else. Nothing has to have been built for that site in advance, so **naming a site is worth doing even when you expect nothing to exist for it.** The descriptions are the site's own words, every tool it exposes is callable (including ones that change something there), and site tools are free. **The other two tiers come back too.** CAPABILITIES (`bowmark.flights.search(...)`) are the default and usually what you want: one call fans out across several sites, dedupes, ranks, and routes around a site that's failing. PROVIDERS (`bowmark.providers.kayak.search(...)`) are the individual sites, callable directly — they appear only when your query NAMED a company, or when the capability has just one provider behind it. A direct provider call gets that site's own raw shape and no failover, so prefer the capability unless you specifically want that site. Loop: call `get_library` → write a JS script against the `bowmark` global → send it to `run`.

Return the dashboard link for one stored secret this account holds, so you can answer "where is my Acme password?" with somewhere to go. **It returns a URL, never a value** — opening it requires the user to be signed in and to confirm who they are, and only their own browser can read what comes back.

List the saved logins this account holds — the `id` to name in a later signed-in call as `{ connection }`, which site, which account, whether it is still good, and when it was last used. A live one means a script can reach that site's signed-in pages with no sign-in step and usually no browser. Useful before a task that needs an account: a connection marked `needs_reauth` or `expired` is why a run would pause and ask the user to sign in again. Adding a NEW login is still the user's to do, at https://bowmark.ai/dashboard/connections — `delete_connection` only forgets one this account already holds.

List the stored secrets this account holds, by NAME. Returns name, type, which hosts each may be used against, when it expires and when it was last used — never a value, and no Bowmark endpoint returns one. **Call this BEFORE `request_secret`.** A secret the user has already set is ready to use; asking for it again sends them to a page for nothing. In a script, refer to one by name: `bowmark.secret('acme_pw')`.

Sign a saved login out by the `id` `list_connections` returned. Bowmark drops the cookies it held, and where the site supports it (`siteLogout: "supported"` in the reply) the session is ended ON THE SITE too — `siteSignedOut: true` means Bowmark checked the site no longer accepts it. The saved login is KEPT, status `logged_out`, so the user can sign back in to the same entry later. Call this when the user asks to sign out of a site. `delete_connection` is the other action: it forgets the entry entirely and leaves the site session alive.

**Creates a free Bowmark account and returns an API key.** Call it when a `run` is refused for hitting the anonymous limit, when you expect to make more than a handful of calls, or any time the user says they want an account. **Every argument is optional. `register({})` is a complete, valid call** and returns a working key. Do NOT stop to ask the user for anything before calling this — there is nothing required to ask for. WHAT IT BUYS: anonymous callers share one small daily allowance per IP address with everything else behind it. A registered account gets its own monthly allowance, an order of magnitude larger. The response says both numbers. Where the connection allows it the new allowance applies IMMEDIATELY, with no configuration change — `activeNow: true` in the response means your very next `run` is already on it. `email` is OPTIONAL and no key depends on it — it is not a credential, and nothing you do with the API authenticates with it. **But passing one CREATES A BOWMARK SIGN-IN for that address**, so the person can sign in at bowmark.ai with an emailed code and manage the account without keeping any link. Pass it only if the user actually gave you one. **Never invent one and never pass a placeholder** — that creates a sign-in for somebody else's mailbox. **IF YOU PASS AN `email`, TELL YOUR USER THIS:** that address is subscribed to occasional Bowmark product and changelog email by default. Pass `newsletter: false` to decline, and say so plainly rather than deciding for them — every message carries a one-click unsubscribe either way. With no `email` there is nothing to subscribe and nothing to mention. `promotions` is a SEPARATE consent and is OFF unless you set it. **Only set it if the user has actually said yes to promotional email.** Do not infer consent from enthusiasm, and do not set it to be helpful. AFTER IT RETURNS: show the user `apiKey`. It is returned exactly once and cannot be recovered — tell them to save it and to add it to their Bowmark MCP config as `Authorization: Bearer <key>` so it works from every future session. Do not put the key in a file, a commit, or anywhere it outlives the conversation. **HOW THEY REACH THE ACCOUNT AS A PERSON.** If `signInUrl` came back, that is the way in: they sign in there with the email you passed, Bowmark sends a code, and they land in this account. Nothing to save. `claimUrl` is then only a backup for a wrong address. If `signInUrl` is null, `claimUrl` is the ONLY door — show it, and say `claimExpiresAt` is the date it stops working, because after that they can use the key but never manage or revoke the account. Re-registering is not how you get a second key: an address that already has an account is refused, and there is a per-network cap. If you already hold a key, present it instead.

Record what was missing, wrong, or incomplete so Bowmark can build it. Pass the `runId` returned by `run` when this report is about a run; omit it when `get_library` did not cover the task. This records feedback only and does not retry a run.

Report whether the RECIPE ran cleanly — not whether you got the user a good answer. Call ONCE per envelope after you finished walking the recipe OR abandoned it. `success: true` = every step executed AS WRITTEN. Each locator resolved on the first try, no extra clicks/scrolls/waits beyond the recipe, no JS-eval workarounds, no skipped steps, no substituted selectors. If you walked the recipe clean, report true — even if the answer turned out wrong (answer correctness is a separate concern). `success: false` if ANY of these happened, even when you eventually helped the user: a locator missed, a click did nothing, you retried with a different selector, you fell back to raw browser code (`browser_run_code_unsafe` etc.), you scrolled or clicked extra to recover state, you skipped a step, the recipe led somewhere unexpected. Honest failures trigger a re-crawl that fixes the recipe; false `true` silently degrades it for everyone. Quick check before reporting: if your tool-call sequence since the recipe started is longer than the recipe's step list, that's `false`. If you used raw browser code, that's `false`. Skip when: `ask` returned a miss (no `id`); user interrupted mid-execution; you read the envelope but didn't execute it; task is still waiting on user input.

Create a named, empty slot for a secret and get back a link the user opens to fill it in. They type the value on a Bowmark page and choose how long it lives, from 5 minutes to never. It is encrypted in their own browser before it leaves, so nothing on the way — this connection included — ever sees it. **Give the user the link. Never ask them to type a password, API key or one-time code to you.** A secret in this conversation is in your context, in the transcript and in the logs. **Name it for the person, not for your script.** The name you pass is the heading on the page they open and the row they see in their secret list months later, so make it `<site>_<what it is>`: `letterboxd_password`, `stripe_api_key`, `acme_totp_seed`. A run id, a timestamp, a uuid or a bare `password` is refused. Call `list_secrets` first: if the name already exists and is set, use it instead. `name` is lowercase letters, digits, `_`, `.` and `-`. `hosts` narrows where the value may be used and is worth passing — a secret is refused against any other site.

**Executes the task on the real websites** (the search, the price check, the availability lookup, the configurator, the booking flow) and returns what came back. Runs a script you authored against the `get_library` vocabulary, on the live sites, and returns `{ ok, result, logs, error, ms }`. Call `get_library` FIRST — it gives the exact function names, argument shapes, and return types; this description is the LANGUAGE + how-to (get_library is just the vocabulary). THE LANGUAGE — plain async JavaScript: • `bowmark` is a ready global (no import). Call capabilities off it — `await bowmark.<capability>.<method>(...)` — always `await`, they're async. • Individual sites are callable too, at `await bowmark.providers.<provider>.<fn>(...)`. Use one when you specifically want THAT site; otherwise prefer the capability, which fans out across sites and routes around failures. • Real control flow: `await`, `if`, loops, array methods (`map`/`filter`/`sort`/`slice`), and `Promise.all` for fan-out. • `return` a value to get it back (JSON-serialized). `log(...)` for progress lines. • Standard JavaScript built-ins are there (`JSON`, `Math`, `Date`, `RegExp`, `Intl`, `Promise`), plus `URL` and `URLSearchParams` — use them to resolve a relative link against the page it came from and to build query strings. Nothing else from the Web platform exists: no `fetch`, `setTimeout`, `TextEncoder` or `crypto`. • `bowmark` is the ONLY I/O — no `fetch`, `process`, filesystem, or `import`/`require`. Write a plain async body, not a wrapping function. • `bowmark.files` keeps a file the run produces (a CSV, an image, a transcript) in the caller's Bowmark account and gives you a link to it: `save({ name, text | base64, contentType? })` → `{ id, url, expiresAt }` (25 MB from a script), `list()`, `get(id)`, `url(id, { expiresIn })`, `makePublic(id)` → `{ publicUrl }`, `makePrivate(id)`, `delete(id)`. Return the link rather than inlining the bytes. • Keep scripts small and deterministic — no infinite loops. Runs in a hard sandbox with CPU + memory + wall-clock limits. **Your own tool-call budget is tighter than you'd guess, and it decides how many calls fit in one script.** Most MCP clients time a single tool call out at around 55 seconds, and ONE ordinary capability call already spends 30-55 seconds of that fanning out to live sites — see COMPOSITION below before calling a second capability in the same script. SENDING IT: pass the script text as `run({ script })` — `script` is the only argument (there is no `site` argument; the library exposes every capability under `bowmark`). `result` is whatever you returned; `logs` are your `log()` lines in order; on a throw/timeout `ok:false` and `error` is set. CHECK `status` BEFORE `ok`. It is `ok` | `error` | `partial` | `needs_user`. • `partial` means the script RAN and `result` is real and usable, but some of what it called never answered — so the result is narrower than what you asked for. `ok` is still `true`; this is not a failure. `incomplete.summary` says what happened in one sentence, `incomplete.failures` names each call that threw and what the site said, and `incomplete.degraded` names each call that answered while reporting its OWN results thin. You MUST say so when you present the result: name what was missed, and do not describe it as complete, exhaustive, or 'all' of anything. A `partial` you report as whole is a wrong answer, not a slightly smaller right one. • Before you conclude a `partial` is final, check `incomplete.failures[].fixable`. `fixable: true` means YOUR ARGUMENT was rejected, not the site — the error text names what that function actually takes, so re-read it in `get_library`, fix the argument and run again; that recovers the whole answer. For any other failure re-running usually returns the same thing. • When a fan-out capability (shipping, flights, hotels, cars, etc.) fails on EVERY provider, `incomplete.failures[].dropped` carries the per-provider breakdown as an array of `{ provider, fn, reason, detail }` — branch on that instead of parsing the prose in `.error`. • `needs_user` means a site needs the USER signed in — it is NOT a failure and NOT something you can fix by editing the script. `needs` lists the sites; `meta.handoff.url` is a single-use link that expires (`meta.handoff.expiresAt`). Give the user that URL, say which sites it covers, and WAIT. When they tell you they're done, send the SAME script again unchanged. Do NOT retry before then — it will stop at the same place and cost another run. Do NOT try to log in yourself, ask them for a password, or work around it with a different site. • Logged-in runs need a Bowmark API key on the connection; if you get `needs_user` saying so, tell the user to add one rather than retrying. ONE EXIT IP FOR THE WHOLE SCRIPT: `await bowmark.egress.pin({ ttlMinutes: 120 })` before your first call, and every call the script makes afterwards leaves from ONE address. Reach for it when a site binds a cart, a token or a sign-in to the address that made the request, and the symptom is being logged out or asked to start over between steps. It is not a dedicated IP: the exit is a shared residential peer, `shared: true` says so, and the vendor can still replace it without telling us. **Pin FIRST** — a site you already called keeps the address it used, and the result says `pinnedAfterCalls: true` when you left it too late. Up to 7 days; anything longer comes back clamped, and the `ttlMinutes` you get back is the one that was granted. A DEDICATED IP, IF `pin` ISN'T ENOUGH: `pin` is free and shared — a stranger's device, gone in at most 7 days. `bowmark.egress.lease` is the other product: a static IP nobody else is ever served, ordered for a real term and charged to the account, for a site whose session dies even on a pinned exit. Reach `bowmark.egress.quote({ country })` first — it returns your own price for that country's real availability, read live; never assume a term or a number. `lease({ country, idempotencyKey })` places the order (`idempotencyKey` is yours to choose, so a retried call cannot buy two); it is STATIC ISP ONLY today, real money, and there is no refund — confirm with your user before calling it, the way you would before any other purchase. `list()` and `get(id)` read what the account already holds; `use(id)` routes this run's later calls through one specific lease; `release(id)` stops auto-renewal (the IP keeps working for its already-paid term, then goes away for good). SAVED SECRETS: `savedSecrets` lists every secret the run stored in the user's Bowmark account, each as `{ name, type, viewUrl }`. An API key a key-making function returns is saved there automatically as `<vendor>_api_key`, and later runs that call that vendor use it with nothing to configure. When `savedSecrets` is present, tell the user what was saved and give them each `viewUrl`, where they can view or manage it. `trace` is the execution trace — every capability you called and the providers it fanned out to under the hood: `[{ kind:'capability', capability:'flights', method:'search', ms }, { kind:'provider', capability:'flights', provider:'google_flights', fn:'search', results, status, ms }, …]`. The script never visits websites — it calls capabilities that route to providers, and the trace is the receipt. COMPOSITION MEANS PARALLEL, NOT SEQUENTIAL, AND THAT GOES FOR PROVIDER CALLS TOO — an `await` inside a `for` loop is the single slowest thing you can write here. Measured 2026-09-18 over 147 real runs: a script with one awaits a for-loop body ran a median of 49 seconds against 19 for the rest, and on YouTube transcripts specifically, three fetched one after another took 27.3s where six fetched together took 9.8s. Collect the ids first, then `Promise.all` over them; never walk a list awaiting each item. Default to ONE capability call per script — most already spend 30-55 seconds of your own ~55-second tool-call budget on their own, so a second call made AFTER the first routinely never returns before your client gives up, and the script errors with nothing to show for either call. If you genuinely need several, run them TOGETHER inside `Promise.all` — in parallel they cost about what one call costs, not the sum of them — and never call them one after another. To sweep a date range, call the search per date inside `Promise.all` and sort/filter the merged array (each flight result carries its `date`, so you can tell the runs apart). See the `get_library` examples for the exact shape. If even one call will not fit your budget, narrow the query (fewer dates, a single site instead of a fan-out) or split the work across separate turns — do not compose more into one script to make it fit. A FAN-OUT OF FIVE THAT LOSES ONE SHOULD STILL HAND BACK FOUR: `Promise.all` rejects the whole thing the moment any leg does, so one refused request turns a finished answer into nothing. Use `Promise.allSettled` and keep the fulfilled legs. That is safe HERE and nowhere else, because Bowmark reports the dropped leg for you — the runtime counts what your script CALLED at the dispatch point, not what it chose to report, so a swallowed failure still comes back as `status: 'partial'` with the call named in `incomplete`. Say so when you present the result. SOME capabilities return their rows alongside a `warnings` array — `{ flights, warnings }`, `{ hotels, warnings }`, `{ cars, warnings }`. Others return a bare array. The signature in `get_library` tells you which; go by it rather than assuming. Where there IS a `warnings` array it names any site dropped from the fan-out, and the rows themselves look identical with or without it. Read it, and pass on anything it says rather than quoting a 'cheapest' that only ranks the sites that happened to answer. Dropping `warnings` from what you return does not hide it — the run comes back `status: 'partial'` regardless, because the runtime counts what your script CALLED, not what it chose to report. **`bowmark.delegate` hands a task to a coding agent (Claude Code) in a fresh, throwaway Linux machine** — for work that needs a real computer: write and run code, work in a git repo, install packages, process files. It is billed to the account for machine time and model tokens, under `maxCostUsd` (default $5), so tell your user it is running and that it costs money. `start({ prompt, env?, repo? })` returns `id` at once; pass any token the task needs in `env`, never in the prompt. In **later runs** call `status(id, { waitMs: 60000 })` until it is `idle`, then read `result`, `files` and `diff`, and `stop(id)`. `send(id, message)` continues the same conversation. It is not for reading a website — use the library or `browser_agent` for that. `get_library({ query: "coding agent" })` has full types and examples. **`bowmark.browser_agent` is a one-shot live browser for ONE task on a site nothing in the library covers** (a lookup came back empty, or a function failed on it). It is billed per turn to the account, and it is not a watcher: it cannot poll on a schedule or run unattended, so a standing watch or daily job is not a fit — say so. When it fits and your user asked you to get the thing done, `start({ task })`; it returns `id` and `watchUrl` at once, and in the same reply tell them it is running, that it costs money, and give them `watchUrl`. A login only they hold does not stop it — they sign in themselves on the live browser through that link. If you hold off for any reason, still NAME it in your reply with its cost — never end on a manual workaround without mentioning it. In **later runs** call `status(id, { waitMs: 60000 })`. When status is `needs_input`, relay `question` to your user and `send(id, their_answer)`. When `idle`, read `result` and `stop(id)`. **Always `stop` a session when done** — idle browsers keep spending money. Your account holds max 3 concurrent sessions. One task = one goal: never bundle multiple queries into one task or the agent silently reuses results. Start separate sessions for each. A NORMAL task takes 1-4 poll cycles to reach `idle` — roughly 1-3 minutes total, not one. Each poll's `steps` shows the agent's current activity, and the SAME step name on back-to-back polls (or a run of DIFFERENT step names) is ordinary mid-task activity, not a stall — do not `stop` a run that is still inside that window just because progress looks repetitive. `get_library({ query: "browser agent" })` has full types and examples.