Skip to main content
Glama

Server Details

Somewhere — Build and maintain web apps

Ownership verified
Status
Healthy
Uptime
100.0% over the last 24 hours
OAuth
Works in Glama
Last Tested
Transport
Streamable HTTP · MCP 2025-11-25
URL
ChatGPT
–
Claude
–

TDQS

A3.5/5.0

Scored across 104 tools

Disambiguation3/5

Most tools have distinct resource/action targets, but the 104-tool surface contains several overlapping clusters: project_archive vs project_undeploy vs project_delete, project_rollback vs project_restore_version, site_check vs site_check_status vs site_verify vs browser, and fs_search vs project_grep vs search_query. The descriptions usually clarify the boundaries, so an agent can disambiguate, but only after reading lengthy contracts.

Naming Consistency3/5

Names are consistently snake_case, but the convention mixes prefixed resource/action names (project_deploy, fs_write, db_query) with bare-noun tools (account, advisor, catalog, docs, env, errors, feedback, browser, api) and verb-like one-offs (ingest, run_code). It remains readable, but there is no single predictable verb_noun pattern throughout.

Tool Count1/5

104 tools is far beyond a well-scoped MCP surface and exceeds the rubric's 50+ threshold for extreme mismatch. Even for a broad platform, the set is too large to scan reliably without catalog/load indirection, and many capabilities could be grouped or lazy-loaded more aggressively.

Completeness4/5

Coverage is unusually broad: projects, deploys, database, files, auth, AI, payments, cron, jobs, email, push, analytics, browser, search, and support are all represented, with an api escape hatch for missing endpoints. Minor gaps remain (e.g. no visible queue/rate-limit/telegram/live-update tools and only db_webhook_get for webhook management), but agents can work around them.

Publisher details

Operator
Somewhere.cloud · Publisher source
Vendor relationship
First-party
Restrictions
Free Account required

Available Tools

104 tools
accountA
Read-onlyIdempotent
Inspect

Which somewhere.cloud account is this session connected as? Takes no arguments and reads only the caller's own account.

It answers "who am I connected as" without a guessed route or an identity inferred from the project list.

Example:

{}
// Returns: { "id": "u_abc", "email": "alice@example.com", "name": "Alice",
//            "anonymous": false, "email_verified": true, "tier": "builder",
//            "summary": "Connected as Alice (alice@example.com). The email address is verified." }

This is the DEVELOPER ACCOUNT holding the projects. For the end user of a customer's app, auth_me with that user's app token answers instead.

Inputs: no named parameters.

advisorAInspect

Ask how to build or diagnose a problem using the current public platform contracts. It takes the question and the facts for the Advisor to use. It cannot read your projects, account, files or earlier conversations, fetch URLs, or call tools.

Questions can span auth, payments, data and other platform features. If facts are missing, the Advisor names the context it needs; your agent reads that context with its own credential and asks a new question. Plan prices and limits come from the public catalogue; your account's usage or pricing version must be supplied explicitly.

For example: { "question": "How do I combine owner() notes with one public intake handler?" }

A durable start returns a run handle. Resuming that handle begins or recovers the same inference; a timeout does not start a replacement run. Each request has one inference. The response contains advice, not executed actions.

Inputs: run_id, context, question, operation.

ai_catalogA
Read-onlyIdempotent
Inspect

List every AI model the platform offers — feature, model id, provider, pricing string, and whether it's free for Builders. Paid-model rates vary by plan and are listed at /v1/pricing. It lists what is available before a model is chosen for ai_complete, ai_tts, ai_generate_image, ai_remove_background, or embeddings.

Read-only. No activation needed.

Example:

{}
// Returns: { "free_tier": { ... }, "markup_rate": 0.05, "models": [{ "feature": "tts", "model": "hexgrad/Kokoro-82M", "provider": "deepinfra", ... }, ...] }

Inputs: no named parameters.

ai_completeAInspect

Call a platform AI model for a project. ai_catalog lists current models and prices; docs({topic:"sw.ai"}) explains the full contract.

With neither provider nor model, the call uses free gpt-6-luna: 10 requests/minute and 200/day per project owner on every plan, 8,192 estimated input tokens including system/tools/history, and at most 1,024 output tokens. Standard service, reasoning disabled, 20-second provider deadline including the body. No paid fallback, BYOK charge, or automatic paid repair.

Explicit provider/model selection uses that model's normal billing path, including explicitly selecting gpt-6-luna. Included workers-ai models retain their separate limits. ai_catalog lists the valid model IDs.

messages is a JSON-stringified array of {role,content}. For text use result.text; result.content contains text/tool_use blocks. With response_schema, the result carries result.parsed and result.parse_error. Paid OpenAI/Anthropic responses may report pending cost: unknown is not zero, and repeating a successful model call does not settle accounting.

Tool-capable models accept Anthropic-shaped tool definitions and tool_result messages. A caller-chosen conversation_id together with subject_type and subject_id retains history under that scope; that caller key continues the conversation on later ai_complete calls. ai_conversation_list, ai_conversation_delete, and ai_conversation_fork take the same scope. Later turns send only new messages. History works across supported providers. Free-default overflow truncates history for the request and never runs paid summarization. For larger conversations and explicit paid compaction read docs({topic:"sw.ai"}).

Structured output: pass response_schema as a JSON-stringified JSON Schema, without caller tools or streaming.

Inputs: messages (required), project_id (required), model, tools, +11 more.

ai_conversation_listA
Read-onlyIdempotent
Inspect

List the saved AI conversations for one subject, or fetch one with its messages. subject_type and subject_id are required so conversation history never falls back to a project-wide view. Without conversation_id it lists (most-recently-updated first; each row includes id, created_at, updated_at, message_count, summarized_message_count, and summary_updated_at). With conversation_id it fetches that single conversation — returns its summary (rolling text from compaction:"summarize", null otherwise), summary_updated_at, and the message log in chronological order. By default a fetch returns only live (non-summarized) messages, matching what the model sees on the next call; include_summarized:true also returns rows folded into the summary.

Inputs: project_id (required), subject_id (required), subject_type (required), limit, +2 more.

ai_generate_imageAInspect

Need a hero, product image, social card, thumbnail, or draft visual? ai_generate_image creates it from a text prompt without wiring a separate image provider. Returns image bytes (base64) or a stored path plus cost.

Two managed models, priced in ai_catalog. Which model: omit model for fast, low-cost drafts (@cf/black-forest-labs/flux-1-schnell, fixed 1024×1024, billed per tile and step); gpt-image-2.5-flare suits final assets, legible text, UI mockups or a transparent background (reserves balance up front; a successful call uses reported token usage capped at that reservation, or the calculator estimate when usage is missing). Failed GPT Image calls return the reservation; an unconfirmed return is reported as settlement: 'unconfirmed'. Earlier retired managed models are refused with a message naming the default. For any other model, bring your own provider: store the vendor's key as a project secret and call the vendor from your own function; there is no managed AI charge on that path (the vendor bills you directly; your function's ordinary platform usage still applies).

Inline rendering: Pass inline: true to get the image as an MCP image content block alongside the JSON result. An MCP client that supports image content blocks can render it directly. Default inline: false keeps the response lightweight (base64 only when not stored).

Example:

{
  "project_id": "my-saas",
  "prompt": "A minimalist logo for a fitness app, clean lines, blue and white",
  "inline": true
}

Inputs: prompt (required), project_id (required), model, steps, +6 more.

ai_ttsAInspect

Synthesize speech from text. Returns audio bytes as base64, or saves to a storage path.

Without model, the free default voice is used — no activation, no bill, nothing to choose.

  • inworld-tts-2-flash (default) — free: 166 English voices by name (default Ashley; e.g. Dennis, Olivia, Duncan). A Kokoro voice id maps to a similar voice. Up to 2,000 chars per call. word_timings: true also returns per-word start/end seconds.

  • hexgrad/Kokoro-82M — free: 28 English voices by id (default af_bella). Up to 8,000 chars.

  • ResembleAI/chatterbox-turbo — free: one built-in voice (omit voice). Up to 8,000 chars.

All are free within fair-use limits; ai_catalog lists every voice. A voice whose provider is down returns VOICE_UNAVAILABLE; nothing is substituted.

Activation required: ai_tts.

Example:

{
  "project_id": "my-saas",
  "voice": "Ashley",
  "text": "Welcome to our app! Let's get started.",
  "storage": "/audio/welcome.mp3"
}
// Returns: { "storage_path": "/audio/welcome.mp3", "size_bytes": 40320, "cost": { "total": "$0.00" } }

Inputs: text (required), project_id (required), lang, model, +3 more.

ai_usageA
Read-onlyIdempotent
Inspect

Return this month's AI spend broken down by feature (transcribe, tts, generate_image, complete). Read-only; no charges.

Example:

{}
// Returns: { "complete": { "calls": 142, "cost": "$0.23" }, "tts": { "calls": 12, "cost": "$0.003" }, ... }

Inputs: no named parameters.

analytics_queryA
Read-onlyIdempotent
Inspect

Query product analytics. Filter by event name and time range; group by hour, day, event, or user. Returns aggregated counts and numeric sums.

Example:

{
  "project_id": "my-saas",
  "event": "purchase_completed",
  "from": "2026-04-01",
  "to": "2026-04-20",
  "group_by": "day"
}
// Returns: [{ "date": "2026-04-01", "count": 12, "sum_amount": 587.88 }, ...]

Inputs: project_id (required), to, from, event, +2 more.

analytics_trackAInspect

Building anything with users? analytics_track gives the app per-event product analytics with one call. Track the moment a user signs up, starts checkout, purchases, publishes, or completes another product action; analytics_query returns it within seconds. Up to 20 numeric properties are automatically aggregatable (sum/avg).

Example:

{
  "project_id": "my-saas",
  "event": "purchase_completed",
  "user_id": "u_alice",
  "properties": { "amount": 49.99, "plan": "pro", "source": "landing_page" }
}

Inputs: event (required), project_id (required), page, user_id, +3 more.

apiA
Destructive
Inspect

Call platform /v1 endpoints that do not have a dedicated MCP tool yet. Dedicated tools cover common operations; this tool covers the remaining and newly added endpoints. catalog lists existing tools and docs({ topic }) documents endpoint shape.

Each request is explicit and inspectable: calls is a flat array of independent { method, path, body? } items. A single invocation runs up to 10 calls, each still endpoint-auth and quota gated. Data from one call is not inserted into another; data-dependent chains run across separate tool calls. path must be a platform /v1/... path, not a full URL.

Write calls require confirm:true by default. GET and HEAD run without confirm; POST /v1/ai/complete and POST /v1/ai/embed are the only read-shaped write routes currently allowlisted. Without confirmation the tool returns the exact calls it would run and asks you to re-call with confirm:true. Calls run with the caller's own auth and the same permission checks as dedicated tools.

Inputs: calls (required), confirm.

auth_cli_pairAInspect

Mint a short-lived smt_ API key for ephemeral environments (hosted coding environments, sandboxes, containers). somewhere auth set takes the returned key through standard input or the command environment as SOMEWHERE_TOKEN. The CLI verifies and stores it, so the session can use the CLI without a browser login. Positional tokens are refused; the key does not belong in command arguments or chat.

Returns: { id, key: "smt_...", prefix, name, kind: "cli_pair", expires_at, ttl_seconds }. Key auto-expires in 24h; the next session takes a new key. No refresh token is returned here: the pairing response omits the long-lived refresh credential. somewhere auth login gives a CLI session that renews itself; it stores its credentials directly in the CLI config.

For a shell without CLI credentials. The CLI is the scoped package @somewhere-cloud/cli (npm i -g @somewhere-cloud/cli). After pairing, first-class CLI commands cover routine work and somewhere call <tool> '<json>' covers the complete platform tool catalog. Without a shell, the MCP tools are the path.

Security note: scoped to the same user as the caller. Auditable as kind='cli_pair' separately from your main developer key, so a stolen ephemeral token is revocable on its own.

Example flow (run once per session):

1. Call auth_cli_pair() → { key: "smt_...", expires_at: "..." }
2. Set SOMEWHERE_TOKEN to the returned key in the command environment.
3. Run: somewhere auth set   // reads SOMEWHERE_TOKEN
4. Run: somewhere whoami     // confirms identity
5. somewhere deploy          // deploy raw source

Inputs: label.

auth_loginAInspect

Sign in user, authenticate, login user, password check, end-user login — log in an existing end user of your app. Returns user profile, authentication token, and session token.

Example:

{ "project_id": "my-saas", "email": "alice@example.com", "password": "s3cure!Pass" }
// Returns: { "user": { "id": "u_abc", "email": "alice@example.com" }, "token": "eyJ...", "session_token": "st_...", "refresh_token": "rt_..." }

Inputs: email (required), password (required), project_id (required).

auth_meA
Read-onlyIdempotent
Inspect

Get the current end user's profile from their authentication token.

Example:

{ "app_token": "eyJ..." }
// Returns: { "id": "u_abc", "email": "alice@example.com", "email_verified": true, "display_name": "Alice" }

Inputs: app_token (required).

auth_signupAInspect

Register user, create account, new user, sign up, onboard user — sign up a new end user for your app. Returns registration and user metadata; credentials are omitted from MCP output. This result cannot sign an agent in from a transcript. Sign-in goes through the app’s normal secure sign-in flow. Passwords are securely hashed. Intended for server-side code, not browser code.

Example:

{ "project_id": "my-saas", "email": "alice@example.com", "password": "s3cure!Pass" }
// Returns registration and user metadata without authentication credentials.

Inputs: email (required), password (required), project_id (required), name, +4 more.

auth_users_listA
Read-onlyIdempotent
Inspect

List end-user accounts of your app — the people who signed up via auth_signup. Distinct from project_list (your own projects). Returns id, email, display_name, email_verified, created_at, last_login_at. Paginated by created_at descending.

Inputs: project_id (required), limit, cursor, search.

browserAInspect

SEE, inspect, DRIVE and CAPTURE any web page — your app's EYES for perception, a VERIFY harness for QA, AND the one way to turn a page into a picture or a PDF. One call returns a structured health SIGNAL (console errors, page errors, failed network requests), not a raw image to vision-parse; a bad step or wrong shape hands back a correcting error.

This is the ONE capture surface. render_screenshot and render_pdf are aliases of this tool; everything they do lives here, and things neither could do compose freely: a full-page webp of a logged-in view saved to a path you choose, or a PDF invoice, out of the same call.

One tool, several outputs — capture: { "as": "png" | "jpeg" | "webp" | "pdf" }. Printing is an output format, not a different operation:

{ "project_id": "my-saas", "url": "https://my-saas.somewhere.site/pricing",
  "capture": { "as": "webp", "full_page": true }, "storage": "/renders/pricing.webp" }
{ "project_id": "my-saas", "html": "<h1>Invoice #1234</h1><p>Total: $49.99</p>",
  "capture": { "as": "pdf", "paper": "A4" }, "storage": "/invoices/inv-1234.pdf" }

See below the first screen, and watch it move. The default screenshot is the first screen only (the viewport). capture: { "full_page": true } captures the whole scrollable page; the frames action watches a page over a few seconds and returns ONE labelled contact sheet plus measured change:

{ "project_id": "my-saas", "capture": { "full_page": true } }
{ "project_id": "my-saas", "actions": [
  { "click": "#open-menu" },
  { "frames": { "count": 6, "interval_ms": 150, "selector": "#menu" } }
] }

frames takes 2–12 screenshots at fixed geometry, (count - 1) × interval_ms at most 10000 ms, and reports steps[].value.motion (from_ms, to_ms, changed_ratio between consecutive frames, measured times) and visual_change_detected, worded as "visual change detected in the sampled region" — sampled pixels neither prove an animation runs nor that none does. With selector the region is that element's box at the first frame, held fixed, and element_box reports how the element itself moved; when it moved, visual_change_detected is true and the summary says by how much, even if it left the region before the next capture. Captures in the hosted browser are spaced by their measured times (frames[].at_ms), not the requested interval_ms: each takes a few hundred milliseconds, so a 200 ms request can come back 400–700 ms apart. Directly after a click it samples at once, so a short transition is caught. An incomplete capture (deadline, element gone, navigation) fails the step with complete: false and its captured count; it never reports "no change". The sheet comes back inline (re-encoded to fit) and, with a project, stored like a screenshot.

Modes:

  • EYES (perception) — NO project_id, any public url (e.g. { "url": "https://example.com" }): look at / inspect / screenshot ANY page. Ephemeral output — the screenshot returns inline (auto-downscaled to fit) by default; store:true gives a short-TTL signed scratch URL (screenshots[].scratch_url, never durable project storage). No-actions inspect includes the bounded clickable-element map. An explicit include list selects sections; include:["network","dom"] adds the full network table and the map. No auth, no origin-lock — any public URL.

  • VERIFY (project QA) — project_id: drive + assert the deployed app of that project. actions clicks / fills / asserts a flow, and auth:{ "user_id": "…" } runs it as a logged-in user (1h audited impersonation), and screenshots store durably to the project filesystem (screenshots[].fs_path). Origin-locked — a url must be on the project's own origin.

Same engine and the same signals-first report either way. Each completed page run also returns one accessibility_layout line for WCAG AA text contrast, horizontal overflow, and tap targets below the 24×24px WCAG 2.2 AA minimum (24–44px is listed as a note). Those findings are advisory and never change passed.

  • Without actions → a health snapshot by default: console errors, page errors, failed network requests (the 4xx/5xx + dropped calls — the real signal), the rendered page text (rendered_text — grep-able structured text beats a screenshot ~80% of the time), final_url, a small screenshot, and a bounded interactive-element map (dom_outline + testid handles). An explicit include list selects optional sections: include:["network","dom"] retains the map and adds the full per-request network table + redirect chain; include:[] omits both. This is the quick "what does my app look like and is it healthy" call (it replaces a standalone screenshot). That page screenshot comes back inline as an MCP image content block by default (it renders directly in the conversation) while its file path stays in the output as the durable artifact; inline:false skips the inline image and keeps only the path. An oversized capture on a tall/heavy page is auto-downscaled to fit inline — a no-project_id call still returns a real image in one shot.

  • actions → the same concise action-sequence JSON as the CLI: {click}, {fill,value}, {upload,file,name?}, {select,value}, {wait}, {expect}, {screenshot}, {frames}, {eval}, and {goto} (a path on the app, e.g. {goto:"/club"}). Every item reports ok/fail with a reason, and the first failure stops the sequence.

  • Existing expanded steps remain accepted for older callers; new flows use the shared actions shape above.

  • url with NO project_id → capture/inspection of ANY public third-party page (e.g. { "url": "https://example.com" }), not just your own app. (When you DO pass project_id, url is scoped to that project's origin.) The screenshot comes back inline by default; store:true instead returns a short-lived, auto-expiring signed URL to the full-res image (screenshots[].scratch_url) — handy for a big external capture you'd rather link than inline. It's kept in an ephemeral scratch store and never touches project storage.

  • html → a raw HTML snippet rendered straight to an image (e.g. an OG card). No page navigation, no steps; returns the image inline, or the stored file path when storage is set. This is render_screenshot's html niche, folded in.

  • extract:"markdown" (or include:["markdown"]) → the page as clean MARKDOWN (headings, links, lists, main content) in the markdown field, instead of vision-parsing the screenshot. The cheapest way to actually read a page's content. (The plain rendered text is always in rendered_text.)

  • session_id → ONE live browser page kept alive ACROSS calls (persistent session). Navigate in call 1; in call 2 (same session_id) wait for a 20s stream and screenshot the SAME page — cookies, current URL, and the in-flight stream all survive. The call returns session_id + session_expires_at; a reconnect skips the initial navigation (the page is where you left it — a goto step moves). Sessions are yours only, capped per developer, and idle out after 5 min (10 min hard cap); a failed step keeps the session, and an expired one restarts signed out and says so (session_note). Omitted, it is the default fresh-per-call browser (cache-safe — a session is only for cross-call state).

With a shell: somewhere browser covers navigation, waits, evaluation, screenshots, and flow steps. This MCP tool covers clients without a shell, and cases where an inline image or result is more useful.

It checks what a UI looks like AND whether it works — clicks land, the form submits, the modal opens — and to catch the 500-ing API call a screenshot alone would hide. (run_code proves a function's backend; browser proves the rendered UI.) Signals come FIRST: passed reflects step outcomes only — console_errors / page_errors / failed_requests matter too (a 500 shows there even when every step "passes").

Elements are targeted by selector rather than pixel coordinates.

Shared action-sequence JSON (preferred; the CLI's --actions file uses this exact array):

"actions": [
  { "fill": "#email", "value": "a@b.co" },
  { "upload": "#avatar", "file": "data:image/png;base64,iVBORw0KGgo=", "name": "avatar.png" },
  { "select": "#plan", "value": "pro" },
  { "click": "button[type=submit]" },
  { "wait": ".dashboard" },
  { "expect": { "selector": ".welcome", "text": "Hi", "visible": true, "count": 1 } },
  { "screenshot": "after" },
  { "eval": "document.title" }
]

Files over the 10 MB inline limit come from project files via { "upload": "#video", "fs_path": "/uploads/big.mp4" } (optional name, type; up to 50 MB per call, streamed into the page).

wait is a CSS selector string or a millisecond number. expect requires a selector and at least one of text (substring), visible (boolean), or count (exact non-negative integer); conditions may be combined. A failed action stops the sequence and names its zero-based action index.

Native alert/confirm/prompt/beforeunload dialogs are dismissed by default and listed in the report's dialogs. { "dialog": "accept" } (with "text" for a prompt) right before the action that opens one accepts it; the answer applies to the next dialog only.

Expanded steps remain runtime-compatible for older callers, but are not a second authoring contract. actions is the form for new flows. A failed action aborts the run while preserving console, network, and screenshot state.

Examples:

// See + inspect — screenshot, signals, and the clickable-element map, no actions:
{ "project_id": "my-saas" }
// Drive a logged-in flow as a specific user (impersonation, 1h, audited):
{ "project_id": "my-saas", "auth": { "user_id": "usr_123" }, "actions": [
  { "wait": "h1" },
  { "expect": { "selector": "h1", "text": "Welcome" } }
] }

Inputs: url, auth, help, html, +24 more.

catalogA
Read-onlyIdempotent
Inspect

The caller-visible index of available tools. Three reference surfaces have distinct effects: catalog lists which tools exist; docs({ topic }) returns the static contract for one surface; advisor({ question }) can answer open-ended questions from an authorized live project's state.

catalog returns the directory / table of contents / manifest for every tool available to this caller on the active surface, grouped by category with a one-line summary per group: { categories: { project: { summary, tools: [...] }, db: { summary, tools: [...] }, ... } }. Categories cover projects, deploys, database, files, env vars, end-user auth, email (out + inbox), AI (chat + media), jobs, cron, queue, logs, errors, usage, feedback, domains, search, web scraping, push, rate limiting, telegram, analytics, captcha, payments, live updates, render, stock photos, and platform help.

For admin/operator callers the same response also includes every registered plain-English platform census question, symptom, and authority declaration. That is the discovery call before somewhere_tech_stats({ metric_id }) or debug_project({ identifier, symptom }); no table name or SQL knowledge is required.

Search: search finds a tool by keyword or exact name — e.g. catalog({ search: "auth_signup" }), catalog({ search: "upload url" }). Returns matching tools + their group + how to load each. Most tools are not in the default surface, so an empty default tool-search is not evidence that a tool is unavailable.

Lazy-load: load returns FULL tool definitions for one or more groups instead of the index — catalog({ load: "auth" }), catalog({ load: "db,fs" }), or load: "all". A group-scoped connection (?groups=db,fs on the MCP URL, or the Mcp-Tool-Groups header) limits a session to the tools it needs.

Inputs: load, search, project_id.

cron_createAInspect

Create a scheduled trigger. Schedule is a 5-field cron expression (minute hour dom month dow). It uses UTC by default; an IANA timezone such as America/Los_Angeles gives local wall-clock scheduling with daylight-saving changes handled automatically. Each fire dispatches a job to your handler (at-least-once delivery, so handlers are idempotent). Missed fires during platform downtime are NOT replayed.

Common patterns:

Pattern

Schedule

Every 15 minutes

*/15 * * * *

Daily at 08:00 UTC

0 8 * * *

Every 6 hours

0 */6 * * *

Weekly Monday midnight

0 0 * * 1

Minimum interval. Your plan sets the smallest gap allowed between two fires. cron_list({ project_id }) reports it as policy.min_interval_minutes, alongside policy.max_per_project. A schedule tighter than the floor is refused with CRON_SCHEDULE_TOO_FREQUENT and the message names both intervals. Schedules that already exist are never re-checked — they keep firing on the cadence they were created with.

Example:

{
  "project_id": "my-saas",
  "name": "daily-digest",
  "schedule": "0 8 * * *",
  "handler": "https://my-saas.somewhere.site/api/cron/daily-digest",
  "payload": { "type": "digest" }
}

Inputs: handler (required), schedule (required), project_id (required), name, +3 more.

cron_deleteA
DestructiveIdempotent
Inspect

Delete a cron trigger. Past runs are not deleted — the cron stops firing future ones.

Inputs: cron_id (required).

cron_listA
Read-onlyIdempotent
Inspect

List cron triggers for a project (or all your projects). Each row includes timezone, last_run_at, last_run_status, last_run_job_id, bounded last_error_code/last_error diagnostics, and next_run_at. A task that has never run returns null for every last-run field. job_get with last_run_job_id returns full bounded attempt history. Passing project_id also returns policy — the project owner's plan name, the smallest interval a new or edited schedule may have, and how many scheduled tasks the project may hold.

Inputs: project_id.

cron_runAInspect

Run an existing scheduled task once now through the same job handler used by scheduled fires. This does not change its schedule. The run is recorded in job history with trigger manual. With preview_session_id and preview_id, the task's handler path and payload run once in that exact open preview instead (its code, data, files and mail; one attempt, at most 270 s); the production schedule is only read and never changes.

Inputs: cron_id (required), preview_id, preview_session_id.

cron_updateA
Idempotent
Inspect

Update a cron trigger's schedule, IANA timezone, handler, payload, display name, or enabled state. Sending a new schedule or timezone recomputes the next fire and re-checks the plan minimum (see cron_list policy); every other edit, including resuming a paused task, leaves an existing schedule alone.

Inputs: cron_id (required), name, enabled, handler, +3 more.

db_batchBInspect

Run multiple SQL statements as a single atomic transaction. Every statement commits together, or none do — a single failure rolls the entire batch back. Suited to any logical operation that spans more than one write (account deletion across multiple tables, moving money between rows, denormalized counters). Max 1000 statements per call.

Each statement returns its own { rows, count, changes, last_row_id } in results[i] matching the order you passed in.

Example (account deletion):

{
  "project_id": "my-saas",
  "statements": [
    { "sql": "UPDATE accounts SET status = 'deleted' WHERE id = ?", "params": ["u_abc"] },
    { "sql": "DELETE FROM sessions WHERE user_id = ?",            "params": ["u_abc"] },
    { "sql": "DELETE FROM posts WHERE author_id = ?",             "params": ["u_abc"] }
  ]
}

Inputs: project_id (required), statements (required), draft, target, +6 more.

db_describeA
Read-onlyIdempotent
Inspect

Schema inspection, list tables, show schema, table structure, columns, types — describe the project database. With no table argument, lists visible managed and raw table names with table_planes metadata. Omitted plane prefers a declared managed table; plane:"raw" inspects a same-name raw table. With a table name, returns its column names, types, constraints, and row count.

Example:

// List all tables:
{ "project_id": "my-saas" }

// Describe one table:
{ "project_id": "my-saas", "table": "users" }
// Returns: [{ "name": "id", "type": "TEXT", "pk": true }, { "name": "email", "type": "TEXT", "notnull": true }, ...]

Inputs: project_id (required), plane, table.

db_dumpA
Read-onlyIdempotent
Inspect

Full SQL dump of the project's database — schema (CREATE TABLE / INDEX / TRIGGER) + every row as INSERT statements. The output is standard SQL you can pipe into any SQL database client to restore, or migrate to Postgres via pgloader.

Returns the raw .sql file as a string. One call gives you the complete raw SQL database's schema and rows to take anywhere. A project that keeps its tables in the managed database has no raw SQL database to dump (RAW_DATABASE_NOT_READY); its managed rows are read with db_browse (plane: "managed") and their schema and row counts with db_describe.

Table access declarations and sensitive-column marks are platform policy, not SQL. Their labels travel as comment lines in the SQL preamble and, parsed, as excluded_security_policy.policies (labels only, never applied by a SQL restore); a warning appears only when the list is non-empty. policies: [] on a successful capture means no table-access declarations were found in this capture — it does not establish that access is safe or preserve your application's authorization, and member join definitions and handler authorization are outside that list. After restoring, redeploy db/schema.ts (access rules are set there and take effect on deploy), then verify with db_scope_list.

excluded_security_policy.capture (v1) is the capture receipt, carrying identity, hashes and times only: canonical project_id and database_id (the top-level project_id echoes your reference), sql_sha256 / schema_sha256 / policy_sha256, and policy_observed_at, data_observation_started_at, data_observation_completed_at, binding_checked_at. The hashes detect changed bytes against metadata you retain; they are not a signature, not provenance, and not a cross-store snapshot. Matching binding checks before and after mean the same project, owner and database were observed; they do not exclude a change in between. When capture metadata is present but malformed, or its SQL or policy hash does not match, this tool returns DUMP_INTEGRITY_UNCONFIRMED (502) and no SQL. An absent capture (an older API during a rolling release) means no capture-integrity evidence; the informational policy labels may still be present.

Refusals, never a partial file: DATABASE_NOT_INITIALIZED (409 — the dump never creates a database), DUMP_SOURCE_CHANGED (409), DUMP_SCHEMA_CHANGED (409), DUMP_POLICY_INVALID (422), DUMP_UNSUPPORTED_SCHEMA (422), DUMP_ROW_LIMIT_EXCEEDED (413, above 1,000,000 rows in a table — no truncation and no streaming export; narrow with db_export_csv filters), DUMP_CAPTURE_LIMIT_EXCEEDED (413), DUMP_POLICY_UNAVAILABLE (503), DUMP_CAPTURE_UNCONFIRMED (503), DUMP_SCHEMA_UNAVAILABLE (503), PROJECT_ACCESS_DENIED (403).

Example:

{ "project_id": "my-saas" }
// Returns the full .sql as text — write it to disk and you're portable.

Inputs: project_id (required).

db_migrateA
Idempotent
Inspect

Run explicit SQL schema migrations for SQL-mode projects. New projects use declared data: define tables and access rules in db/schema.ts and deploy raw source; db_migrate does not create their tables. docs({ topic: 'declared-data', section: 'declare-a-table-and-use-it' }) has a complete example. Managed projects refuse DDL with SCHEMA_LOCKED and apply no SQL.

For SQL-mode projects, CREATE TABLE, ALTER TABLE, CREATE INDEX and DROP are supported; multiple statements may be separated by ;. Explicit preview targeting changes only that preview database. Developer-only — app-user JWTs are rejected.

Inputs: sql (required), project_id (required), draft, target, +6 more.

db_queryAInspect

SQL query, run SQL, SELECT, INSERT, UPDATE, DELETE, execute SQL against the project database — the read/write-ROWS entry point. A documented Postgres-flavored syntax subset is translated; the default database keeps its own expression, typing, comparison, and ordering semantics. For example, division by zero returns NULL rather than throwing. The database is created on first use, but tables are not — new projects declare them in db/schema.ts and deploy raw source; db_migrate is for SQL-mode projects. Raw SQL reaches the project's raw SQL database only; on a project that keeps its tables in the managed database, rows are read with db_browse (plane: "managed"), schema with db_describe, and writes go through sw.db in functions.

Schema changes (CREATE / ALTER / DROP) belong in db/schema.ts plus deploy for managed projects, or db_migrate for SQL-mode projects, not here, and not inline in a deployed function's handler: runtime DDL runs on every request, isn't versioned, and hides new tables from the platform's per-user data protections (a table with an owner_id/user_id column is cross-user readable until it's scoped). db_query is for the rows.

Every successful query returns { data: [], count: N, changes: N, last_row_id: X }: data contains returned rows, count counts those rows, and changes counts affected rows. A write without RETURNING has empty data and a zero count even when it changes rows. last_row_id is a number, an exact decimal integer string when the ID exceeds JavaScript’s safe integer range, or null; other transport metadata may also be present.

Example:

{
  "project_id": "my-saas",
  "sql": "SELECT id, email FROM users WHERE created_at > ? ORDER BY created_at DESC LIMIT 20",
  "params": [1704067200]
}

The database has a 30-second hard query ceiling. timeout_ms bounds how long this call waits (default 30000, max 30000) and returns QUERY_TIMEOUT; it does not promise cancellation of work already accepted by the database.

Inputs: sql (required), project_id (required), draft, params, +8 more. Returns: ok, data

db_scope_listA
Read-onlyIdempotent
Inspect

List the table scopes a project has on record (scopes: recorded declarations, which a deploy that did not complete can leave behind) beside live_rules, the rules the live version actually serves, plus tables that LOOK like per-user data (a user_id/owner_id-style column) with no scope on record. An entry in unscoped_user_tables is a finding to inspect under the table's actual access contract, not a verdict: on a managed project the contract is the table's declaration in db/schema.ts (and structured queries on an undeclared table are refused, not run unscoped); on a SQL-mode project it is what db_scope_set recorded, and raw SQL in server functions is unscoped by design. Developer-only.

Example:

{ "project_id": "my-saas" }
// Returns: { "scopes": [{ "table": "bookings", "owner_column": "user_id", "intent": "scoped", ... }], "unscoped_user_tables": [{ "table": "notes", "owner_column": "user_id" }] }

Inputs: project_id (required).

db_scope_setA
Idempotent
Inspect

Withdrawn: this call no longer changes access rules and always refuses with SCOPE_API_WITHDRAWN (HTTP 410). Access rules are set in db/schema.ts (scope: owner() / shared() / member() / serverOnly(), plus a client block for browser access) and take effect on deploy. An existing SQL-mode project that cannot adopt a schema file is told it needs a migration by Somewhere; nothing is changed either way. The in-band sw.db.scope(...) declaration from server code refuses the same way. db_scope_list still shows the recorded declarations beside the rules the live version serves.

Inputs: table (required), project_id (required), intent, owner_column, +1 more.

db_webhook_getA
Read-onlyIdempotent
Inspect

Return the current database change-webhook registration for a project (url, events, secret, last delivery status). Returns { webhook: null } when none is set.

Inputs: project_id (required).

deploy_statusA
Read-onlyIdempotent
Inspect

Read production deploy state on every plan: published state, immutable release, current version and file counts. Preview details require hosted-preview read access. When unavailable, preview_comparison is unavailable and preview comparison values are null; this does not mean the files are in sync. Every production hostname serves the selected production release.

Inputs: project_id (required). Returns: ok, data, error, message

docsA
Read-onlyIdempotent
Inspect

The static manual for one platform surface at a time. Returns signatures, examples, common patterns, failure modes, and exact behavior for deploy, sw.db, sw.auth, files, payments, and other primitives. The tool list names verbs; docs defines their contracts.

This is the static manual; advisor({ question }) provides tailored advice from supplied facts, and catalog lists available tools.

Returns a bounded summary by default: the read-first sections plus an id index of every section. The first line reports view and complete=true|false. section returns one section, and detail: "full" the complete topic.

Topics: adopt, analytics, api-surface, app-mcp, architecture-patterns, auth-client, billing, browser, calendar, changes, cli, common-mistakes, connect-agent, cors, cron, database-engine, declared-data, declared-files, deploy, deploy-intelligence, design-system, dev-environments, domain-ownership, domains, feedback, file-tools, functions, getting-started, github, guarantees, handled-for-you, inspect, limits, live, live-data, local-dev, migration-supabase, payments, portability, postgres, pricing, pricing-comparison, project-groups, projects, recipe-ai-agent, recipe-ai-features, recipe-ai-receipts, recipe-background-jobs, recipe-booking, recipe-csv-import, recipe-ecommerce, recipe-email, recipe-escalation, recipe-file-uploads, recipe-import-app, recipe-login, recipe-multi-chat, recipe-paid-api, recipe-pdfs, recipe-push-notifications, recipe-seo, recipe-signed-in-app, render, rooms, sdk, sdks, search, security-model, setup, smoke, speed, sql-compatibility, sw.agent, sw.ai, sw.auth, sw.billing, sw.db, sw.email, sw.endpoint, sw.env, sw.fetch, sw.fs, sw.groups, sw.image, sw.jobs, sw.logs, sw.notifications, sw.push, sw.rateLimit, sw.web, tasks, test, troubleshooting, typed-functions, verify-before-deploy, vs-supabase, vs-vercel. Aliases such as fetch/http/outbound and ctx.* names also resolve. Unknown topics return this canonical list. Example: { "topic": "sw.fetch" }, then { "topic": "sw.fetch", "section": "<id>" }.

Inputs: topic (required), detail, section, project_id.

docs_queryA
Read-onlyIdempotent
Inspect

Query the source truth of a project — routes, symbols+doc-comments, import graph (depends-on/used-by), tables, task refs, coverage, and bounded rich route contracts — assembled from the source of the project's ACTIVE release. It answers questions about a project without grepping files.

By default the platform selects the sidecar of the exact active release (its ready, same-project version); there is no fallback to a newer or older sidecar. A successful default answer carries version_source: 'active_release', release_id and source_manifest_hash as selection metadata — what was selected, not independent certification of the artifact bytes. version selects an exact older sidecar; that answer carries version_source: 'explicit' and no release metadata. When the active release cannot be resolved (none active, not found, not ready, its source missing or temporarily unavailable) the answer is a neutral release-status error with version_source: 'active_release' and the release_id where one exists — no source hash, and never a claim that you must redeploy. A project whose selected release has no sidecar answers DOCS_SIDECAR_NOT_FOUND (404). Input problems are ordinary validation or project-not-found errors.

The result comes from the deploy-version-keyed docs sidecar selected for that release, not from a live grep. path, symbol, or route returns the matching methods/query actions, schema columns and constraints, sw.* and environment-name bindings (never values), and imported-helper evidence. The response never includes the whole readable Markdown document. If a sidecar is partial or omitted files, the response includes source hash/version/completeness flags so absence is not mistaken for proof that code is not deployed. The private canonical platform artifact is explicitly SOURCE truth, not serving/runtime-effective truth.

Examples:

{ "project_id": "my-saas" }
{ "project_id": "my-saas", "path": "api/checkout.ts" }
{ "project_id": "my-saas", "symbol": "createCheckout" }
{ "project_id": "my-saas", "route": "POST /api/checkout" }

Inputs: project_id (required), path, route, symbol, +1 more.

domain_buyAInspect

Preview a domain purchase and get a secure checkout link.

domain_buy takes project_id + domain. The platform returns the price and a dashboard_checkout_url. The price is quoted verbatim, and the secure checkout link is where payment completes.

Customer purchases cannot be completed through another MCP tool. The user completes payment through the checkout link, and registration begins only after that payment settles.

The domain is registered in the buyer's name — they own it outright and can transfer it to any registrar or account whenever they want. Mention this when sharing the checkout link; details: https://somewhere.cloud/docs/domain-ownership

Example:

{ "project_id": "my-saas", "domain": "acmedash.com" }

The response will be an error of type PURCHASE_CONFIRMATION_REQUIRED carrying the price and checkout URL, e.g. { "ok": false, "error": "PURCHASE_CONFIRMATION_REQUIRED", "domain": "acmedash.com", "price": "$17/year", "confirm_token": "...", "dashboard_checkout_url": "https://somewhere.cloud/dashboard/projects/...?tab=domains&buy=acmedash.com" }. This response is a checkout handoff: payment completes at the dashboard_checkout_url.

Inputs: domain (required), project_id (required).

domain_checkA
Read-onlyIdempotent
Inspect

Check if a domain is available for purchase and get the price.

Example:

{ "domain": "acmedash.com" }
// Returns: { "available": true, "price": "$12.00/year" }

Inputs: domain (required).

domain_listA
Read-onlyIdempotent
Inspect

List custom domains configured for a project, with their verification status.

Inputs: project_id (required).

email_sendAInspect

Adding a welcome, receipt, status, or alert email to an app? email_send sends one transactional email to one recipient on every plan. Without from, the platform-managed sender is used immediately; the project name appears as the sender label. from selects a verified sender domain of the app. Domains bought through us or connected with our nameservers are set up automatically; a domain hosted elsewhere is verified once in Settings → Domains. A caller cannot explicitly name a platform domain.

The platform-managed sender is transactional-only. A verified sender domain carries the branding of the app itself and its marketing email. Outbound transactional email is available on Free, Builder, Pro, Scale, and Enterprise. The plan's email allowance and send rate limit apply either way; current limits are at /v1/pricing. It takes html or text (or both). reply_to is optional.

Example:

{
  "project_id": "my-saas",
  "to": "alice@example.com",
  "subject": "Your order shipped",
  "html": "<p>Tracking number: ABC123</p>"
}

Inputs: to (required), subject (required), project_id (required), from, +3 more.

envA
Idempotent
Inspect

Environment variables, secrets, config and integration keys. It sets with project_id, key and value; deletes with key and delete:true; lists with project_id only. Values are encrypted and omitted from list results. New values are private for server functions by default. A VITE_ or REACT_APP_ prefix alone never publishes a value. Publishing a browser value requires a prefixed name and public:true. Recognized secret credentials, including test credentials, cannot be marked public. Server functions read sw.env.NAME. Browser code reads import.meta.env.VITE_NAME or process.env.REACT_APP_NAME only for explicitly public values. A private browser reference refuses compilation. Provider and purpose are optional descriptive labels, not access controls. After the project adopts live config on a deploy, saves reach new ordinary requests within 60 seconds, usually in a few seconds. Cron and new background deliveries see changes within 5 seconds. Public browser values reach new page loads within 60 seconds. Previews keep the config they captured. List and save responses contain exact references and effective visibility, never values. A project's combined environment values have a 5,120 byte limit.

Inputs: project_id (required), key, scope, value, +4 more.

errorsA
Read-onlyIdempotent
Inspect

Why is my app broken, exceptions, stack traces, failures, recent errors, crash reports, debugging. One trace_id returns the complete ordered parent/child operation waterfall plus its correlated logs, errors, deploy failures, and journey events. No project lookup is required for that one-id path. Without a trace id, project_id returns the last 24h of failures from that project's functions. Each row carries kind: "exception" means nobody chose the outcome (an uncaught throw, or a 5xx) and "refusal" means a handler answered 4xx on purpose — a 401 from your own auth gate is a refusal, not a bug, and kind separates the two.

Example:

{ "project_id": "my-saas", "limit": 20 }
// Returns: [{ "timestamp": "2026-04-20T...", "path": "/api/users/signup", "status": 500, "message": "UNIQUE constraint failed: users.email" }, ...]

Inputs: limit, trace_id, project_id.

feedbackAInspect

End-user app feedback sent to the project's private owner inbox (destination: "project_owner_inbox") — this does not reach the Somewhere platform team. Every successful submission repeats that destination and names the exact platform-support calls. Submit: provide a message about that project's own UI or behavior. List: without message it returns feedback on a project you own. When the project owner resolves one of these reports, the owner-facing project channel can emit a feedback_resolved event.

Platform bugs, missing capabilities, deploy/API problems and documentation issues are out of scope for this tool. support_ticket({ message: "..." }) sends such a report to the platform support queue.

Example:

// Submit:
{ "project_id": "my-saas", "message": "The checkout button in this app does nothing after I enter my card" }

// List:
{ "project_id": "my-saas" }

Inputs: project_id (required), message, page_url.

fs_deleteA
DestructiveIdempotent
Inspect

Delete a file or directory. Directory deletes are recursive — all children are removed. Archived versions are also cleaned up.

Inputs: path (required), project_id (required).

fs_globA
Read-onlyIdempotent
Inspect

Match file paths against a glob pattern. Fast metadata query — no file contents are read, no scan.

Supported syntax: * (not across /), ** (across /), ? (one char), {a,b,c} (brace expansion).

Example:

// All TypeScript files under src/api:
{ "project_id": "my-saas", "pattern": "/src/api/**/*.ts" }

// JS or TS top-level files:
{ "project_id": "my-saas", "pattern": "/*.{js,ts}" }

Inputs: pattern (required), project_id (required), limit.

fs_public_urlA
DestructiveIdempotent
Inspect

Get a public URL for a file written via fs_write. The URL is hosted on the project's subdomain at /storage/{path} and can be embedded directly as an image src, anchor href, etc. — no signing or auth. A file in a declared file collection takes its visibility from db/schema.ts: make_public on it answers FILE_VISIBILITY_DECLARED (docs({ topic: 'declared-files' })).

Files are PRIVATE by default. Asking for a public URL does NOT silently expose a private file: a private file returns an error unless you pass make_public: true to publish it. An already-public file just returns its URL. fs_signed_url gives a time-limited link to a private file WITHOUT making it world-readable.

Example:

{ "project_id": "my-saas", "path": "/uploads/users/alice/avatar.png", "make_public": true }
// Returns: { "public_url": "https://my-saas.somewhere.site/storage/uploads/users/alice/avatar.png", ... }

Inputs: path (required), project_id (required), make_public.

fs_readA
Read-onlyIdempotent
Inspect

Get file, download file, fetch file contents, view file, cat, ls — read a file or list a directory from the project filesystem. If the path ends with / or matches a directory, returns a directory listing; otherwise returns the file content.

There are two file surfaces: deployed source is read with project_files_list / project_file_read; fs_read, fs_write, and fs_upload use runtime storage via sw.fs. Project source such as src/App.tsx or api/foo.ts is read with project_file_read, not fs_read.

Optional lines returns only a line range from a text file as JSON with { content, lines: [start, end], total_lines } — useful for peeking into large files without downloading them whole.

For a directory listing, recursive: true returns every descendant in one call, with an optional depth cap.

Example:

// Read a whole file:
{ "project_id": "my-saas", "path": "/uploads/users/alice/avatar.png" }

// Read lines 50–75 of a stored text file:
{ "project_id": "my-saas", "path": "/logs/import-run.txt", "lines": "50-75" }

// List a directory (immediate children):
{ "project_id": "my-saas", "path": "/uploads/users/" }

// List a directory tree, two levels deep:
{ "project_id": "my-saas", "path": "/uploads/", "recursive": true, "depth": 2 }

Inputs: path (required), project_id (required), depth, lines, +1 more.

fs_replaceA
Idempotent
Inspect

Find-and-replace text in a single file, server-side. No read-modify-write cycle from the client. Archives the current contents as a new version before writing (same retention as fs_write), so fs_restore can roll back.

Literal string match (not regex). Only works on text files. A single find that matches nothing returns replacements: 0 and writes nothing.

Several edits to one file: pass edits, an ordered array of { "find", "replace", "expect"? } (at most 200), instead of top-level find/replace. They apply in order (a later edit sees the earlier ones) and save as ONE new version. In the array every edit must match: the first that does not returns FIND_NOT_FOUND with zero-based data.edit_index and writes nothing; expect: n requires exactly n matches, else FIND_COUNT_MISMATCH with data.expected and data.actual. One call edits one file.

Example:

{ "project_id": "my-saas", "path": "/src/config.ts", "find": "API_URL = 'https://staging...'", "replace": "API_URL = 'https://api...'" }
// Returns: { "ok": true, "replacements": 1, "version": 4 }
{ "project_id": "my-saas", "path": "/notes/todo.md", "edits": [{ "find": "- [ ] ship", "replace": "- [x] ship", "expect": 1 }, { "find": "Status: draft", "replace": "Status: done" }] }
// Returns: { "ok": true, "replacements": 2, "edits": [{ "edit_index": 0, "replacements": 1 }, { "edit_index": 1, "replacements": 1 }], "version": 5 }

Inputs: path (required), project_id (required), find, edits, +1 more.

fs_signed_urlAInspect

Mint a short-lived signed URL for a file. The URL is fetchable without an API key — the token IS the auth. It suits email attachments, image previews, and "download once" handoffs to recipients without a developer key.

expires_in is in seconds, min 60, max 604800 (7 days), default 3600 (1 hour). After expiry the URL returns 403.

Example:

{ "project_id": "my-saas", "path": "/uploads/invoice-2026.pdf", "expires_in": 86400 }
// Returns: { "url": "https://api.somewhere.cloud/v1/fs-signed/eyJ...", "expires_at": "2026-05-13T..." }

Inputs: path (required), project_id (required), expires_in.

fs_statA
Read-onlyIdempotent
Inspect

Get metadata for a file or directory without downloading the contents. Returns path, name, type, size_bytes, content_type, visibility, version, created_at, and updated_at; a file in a declared file collection also returns collection, group (member collections) and owner_subject_id. File tools act with your developer authority over every file in the project.

Inputs: path (required), project_id (required).

fs_uploadAInspect

fs_upload = files. fs_write = text and small inline content. Uploads an image, PDF, video, zip, font, large artifact, or attachment without carrying binary bytes or base64 in tool arguments.

Client capability matrix:

  • Native-file connector clients: file carries a temporary authorized file reference that this tool streams through the upload relay.

  • Clients with raw HTTP access: an omitted file mints a one-time upload_url that accepts raw bytes with the returned Content-Type. This two-step transport keeps base64 out of tool arguments. One request carries at most 100 MB; a bigger file goes up in parts through the returned multipart_url (start, send each part, then complete — the reply spells out the steps). With size_bytes, a file over 90 MB comes back already started, with parts_url, part_size, part_count and complete_url; a size over the plan's per-file limit is refused with PAYLOAD_TOO_LARGE before any byte moves.

  • Other shell-less MCP clients: standard MCP arguments have no protocol-level file input, so upload availability depends on compatible host file references or raw HTTP access.

The connector reference and upload URL are temporary transports, not the durable artifact. After storage, the saved bytes are addressed by path; fs_signed_url provides a private human download and public:true with fs_public_url provides a permanent public URL. The PUT response and native call both return { path, size_bytes, content_type, version }.

file must be a connector-provided file reference. A local path string, URL string, base64 string, or text value is rejected rather than being mistaken for bytes. content_type overrides connector metadata; otherwise MIME is inferred from connector metadata and the filename/path. Files are private unless public:true is supplied.

Native connector call:

{ "project_id": "my-saas", "path": "/uploads/alice/avatar.png", "file": "<attached connector file>", "public": true }

Raw-PUT fallback:

{ "project_id": "my-saas", "path": "/uploads/archive.zip", "content_type": "application/zip" }

Large file (over 90 MB), uploaded in parts:

{ "project_id": "my-saas", "path": "/uploads/video.mp4", "content_type": "video/mp4", "size_bytes": 125829120 }

Inputs: path (required), project_id (required), file, public, +2 more.

fs_writeAInspect

fs_write = text and small inline content. fs_upload = real files. Write UTF-8 text or other small content already present in the tool call to project file storage. Parent directories are auto-created. Overwrites create a new version automatically (history keeps the last 3 versions on Free, 10 on Builder).

Images, PDFs, video, zip files, fonts, large artifacts, and task attachments go through fs_upload, so binary bytes never enter model context. Base64 input remains accepted here only for backward compatibility with existing callers; new binary uploads go through fs_upload.

It holds notes, JSON, CSV, generated source text, and small cached text that is not project code (project code goes through project_deploy).

There are two file surfaces: deployed source is read with project_files_list / project_file_read; fs_write and fs_read are runtime storage for uploads and generated files via sw.fs. Project source such as src/App.tsx or api/foo.ts is read with project_file_read, not fs_read.

Files are PRIVATE by default. A file served at a public URL (e.g. an embedded app image) takes public: true, and fs_public_url returns the URL. Without it the file is only reachable through your authenticated code.

Example (text):

{ "project_id": "my-saas", "path": "/notes/run.txt", "content_type": "text/plain", "content": "upload completed" }

Inputs: path (required), content (required), project_id (required), public, +1 more.

ingestA
Idempotent
Inspect

Point an app at a website and it becomes data: crawl a site, land every page as markdown in the project's files, and index it into the project's search — one call instead of wiring up a crawler, a file store, and a search index yourself. Always runs as a background job (crawls take minutes) — this call returns immediately with a job_id; the jobs API reports its status, and search_query against the "ingest" index returns results once it completes.

The crawl never follows a link off the seed URL's exact host — it can't wander onto another site. Re-ingesting the same URL overwrites the same file and search item rather than duplicating it, so re-running ingest after a docs site updates is safe.

Example:

{ "project_id": "my-saas", "url": "https://docs.example.com", "max_pages": 40 }
// Returns: { "job_id": "job_...", "status": "queued" }

Then, once the job completes:

{ "project_id": "my-saas", "index": "ingest", "query": "how do I authenticate" }
// via search_query — returns hits pulled straight from the crawled pages.

Inputs: url (required), project_id (required), max_pages, path_prefix, +1 more.

job_createAInspect

Will work outlive the user request, need retries, or need a status later? job_create queues a durable background job. The platform POSTs the payload to your handler URL and retries on failure (at-least-once, up to 5 attempts with exponential backoff). Handlers are expected to be idempotent.

It suits work that should not block a user request: image processing, report generation, outbound email batches, webhook deliveries. run_at with an ISO-8601 time and explicit time zone schedules a future start. The job reports scheduled while waiting and reserves a slot in the account's job limit; cancel it to free that slot. It starts at or after that time.

Example:

{
  "project_id": "my-saas",
  "handler": "https://my-saas.somewhere.site/api/jobs/process-upload",
  "payload": { "upload_id": "u123", "user_id": "u_alice" },
  "timeout_seconds": 600
}
// Returns: { "job_id": "j_abc", "status": "queued" }

Inputs: handler (required), project_id (required), run_at, payload, +3 more.

memory_saveBInspect

Log a principle/SOP/supplier/learning/content idea/vision/spec to the org's memory. It records a close-out when what-we-believe changes. Title states the claim as a sentence.

Inputs: title (required), project_id (required), area, body, +2 more.

payments_checkoutAInspect

Create a Stripe Checkout Session for a project. Once the project owner has onboarded, funds settle to their connected account; the response's fee_percent is the platform fee on the session (current rate at /v1/pricing) and Stripe's standard processing fee also applies. Before onboarding, env='dev' checkouts run on the platform's own Stripe test account with no Connect destination — the response includes is_stand_in: true and platform_fee_cents: 0 so card 4242 4242 4242 4242 succeeds end-to-end. env='prod' returns 412 until the owner finishes onboarding. Supports mode='payment' | 'subscription'.

Three payment bases (exactly one per call): line_items (ad-hoc), quote_id (a stored quote from a payments quote — server supplies the amount; one-time only, and may compose with calendar_hold_token + booking_id for an atomic booking checkout), or plan (a catalog plan slug — the /sw.billing subscribe path).

Plan tracking: a developer may pass metadata={"app_user_id":"","plan":""}; app functions use sw.payments.checkoutForUser for their verified signed-in user. The platform binds the user, price, payment account and test/live mode before checkout, then verifies the payment before granting the selected plan. Live subscriptions keep access during payment retries and lose it when unpaid, paused, canceled or expired. Test purchases are recorded separately and never unlock live access; auth and billing readers currently show live access only. Redeploy older apps normally to enable the runtime user proof. Historical or unmatched payments require reconciliation; metadata alone never grants a plan.

Inputs: cancel_url (required), project_id (required), success_url (required), env, +8 more.

payments_eventsA
Read-onlyIdempotent
Inspect

Paginated feed of Stripe webhook events the platform received for this project (from the payments_events ledger). It can drive an in-product activity feed or confirm webhook reception during integration. The webhook handler is idempotent — duplicate Stripe redeliveries appear once.

Inputs: type, limit, before, project_id.

payments_statusA
Read-onlyIdempotent
Inspect

Get the caller's Stripe Connect status: connected, onboarded, charges_enabled, payouts_enabled, details_submitted. Per-account (not per-project). refresh=true forces a live Stripe API lookup (otherwise returns the last-cached DB state).

Inputs: refresh.

payments_transactionsA
Read-onlyIdempotent
Inspect

List recent charges on the project owner's connected account. Returns Stripe's native cursor pagination — starting_after set to the previous response's next_cursor fetches the next page. Default page size 20, max 100. env=prod lists live-mode charges; default env=dev lists test-mode.

Inputs: project_id (required), env, limit, starting_after.

project_archiveA
Idempotent
Inspect

Archive a project. Hides it from your project list and revokes its subdomain. All data is preserved and can be restored with project_unarchive.

Inputs: project_id (required).

project_createAInspect

Create a new project / app / website / site — initialize a project with a subdomain to start building and hosting it. This is the first step for any new app: a web app, API, backend, landing page, SaaS, or full-stack site.

The project starts with the same starter somewhere init writes — a React + TypeScript app with sign-up, sign-in and sign-out, styled views and design tokens (src/styles/tokens.css) — deployed as its first release; when data.starter.status is deployed it is live at https://{subdomain}.somewhere.site. The call waits up to 120 seconds for that deploy. starter.status is deployed, preview, failed (the deploy was refused; starter.error says why) or unknown (no answer in time, or an answer without a release). For failed and unknown, starter.recovery lists the checks to run and the exact project_deploy call (or the equivalent somewhere init command) that ships the same starter.

If a project_create response is lost, the project may exist: look for it with project_get or project_list (by subdomain) before creating again. Repeating the call returns SUBDOMAIN_TAKEN, and a new name makes a second project. data.starter lists the deployed files and returns the starter's agent_contract (its AGENTS.md), readme (the file map) and skills index; deploys do not publish those files, so they arrive here. project_patch edits the starter. starter: "auth,private-data" adds per-user notes backed by db/schema.ts; starter: "none" creates an empty project.

New projects use declared data: tables and access rules live in db/schema.ts, deployed as raw source. Pages use the generated somewhere:data client for normal data, and a function only for a write the grant cannot express: docs({ topic: 'declared-data', section: 'declare-a-table-and-use-it' }), then docs({ topic: 'recipe-signed-in-app' }) for a public form that files a row for an owner. The subdomain must be unique platform-wide and cannot use reserved names (api, admin, www, etc.). Projects and deploys are unlimited on all tiers.

Example:

{ "name": "Acme Dashboard", "subdomain": "acme-dash", "description": "Internal team dashboard" }
// Returns: { "data": { "id": "…", "url": "https://acme-dash.somewhere.site", "starter": { "status": "deployed", … } } }

Inputs: name (required), starter, template, subdomain, +2 more.

project_deleteA
DestructiveIdempotent
Inspect

Request deletion of a project. Two-step flow.

Step 1 — project_delete takes just the project_id. The platform returns a 6-digit confirmation code that expires after 10 minutes. No project state changes before the code is confirmed.

Step 2 — Human authorization is required before calling project_delete_confirm with the same project_id and code. Confirmation immediately takes the project and its hostnames offline, blocks new project effects, retains its database, files, functions, environment variables, and domain bindings for 30 days, and schedules permanent erasure after that retention period. Recovery during the retention period requires support.

Example:

{ "project_id": "my-saas" }

The response is a SUCCESS carrying the code and a machine-readable status, e.g. { "ok": true, "status": "needs_confirmation", "confirmation_code": "482917", "code": "482917", "next_call": { "tool": "project_delete_confirm", ... } } — minting the code is this step's whole job, so it is never an error. The response carries confirmation_code (code is the same value, kept for existing callers). The response carries no error_code and no canonical_error, so branching on those stays a reliable failure test.

Inputs: project_id (required).

project_delete_confirmA
DestructiveIdempotent
Inspect

Confirm project deletion using the 6-digit code returned by project_delete. Human authorization is required. Confirmation immediately takes the project and its hostnames offline, blocks new project effects, retains its database, files, functions, environment variables, and domain bindings for 30 days, and schedules permanent erasure after that retention period. Recovery during the retention period requires support.

Example:

{ "project_id": "my-saas", "code": "482917" }

Inputs: code (required), project_id (required).

project_deployAInspect

Deploy / ship / host / push / release your app — upload raw source (HTML, CSS, JS, server functions) to a project and put it in production at https://{subdomain}.somewhere.site. The platform compiles your code; you deploy source, not a build.

If you can run a shell, LEAD WITH the CLI: somewhere deploy reads files straight from disk (no inline JSON payload) and is the faster path. The CLI installs with npm i -g @somewhere-cloud/cli && somewhere auth login (shares MCP auth). This MCP tool is the inline fallback — for agents without shell access, small projects, or when the CLI isn't available.

For UPDATES to an existing project, project_patch with find/replace ships surgical edits in ~200 bytes instead of resending every file. project_deploy is for the FIRST deploy of a new project, or for replacing the whole tree.

Large or binary files are referenced, not pasted. Instead of being inlined into files, a big asset (or base64 bytes) goes to project file storage first with fs_write and is referenced by storage path via file_refs (text files) or binary_file_refs (images, fonts, other binaries). The platform resolves the referenced content server-side at deploy time, so a big tree ships without a giant inline payload. Inline files/functions keep working and can be mixed with refs in the same deploy.

Deploys your app. The result lands at https://{subdomain}.somewhere.site and on any verified custom domain — every deploy reaches production.

⚠️ Omitted items are NOT all treated the same. Static files are full-replacement: anything you omit from files is deleted (scope:"functions" leaves static untouched). functions are merge-preserved by default: a function already in production but omitted from this call is KEPT, not deleted — so you can ship a backend-only change without resending the frontend, and project_patch-only functions survive a later full deploy. replace_functions:true makes a deploy delete functions it no longer ships. (Env vars, database, and uploaded fs files are never affected.) Use dry_run:true to inspect exactly what will be added / removed / modified before anything is written. project_patch with a files map changes several files of an existing project without resending the rest: files not listed are kept.

Server-side functions are the core — handler code goes in the functions map (keyed by path, e.g. "api/hello.ts") and becomes routable at /api/... on your production URL. The files map is for STATIC assets only (HTML, CSS, client-side JS, images). Handler code (api/*, _lib/*, root [id].ts routes) belongs in functions, not files — a static asset never routes, so /api/* would just serve the app's HTML. (A handler-shaped path found in files is moved into functions with a warning.)

For a JSON route in api/, use export default sw.endpoint({ auth, handler }) and set auth explicitly. TypeScript infers the handler inputs and sw context. Use auth: 'none' only for a deliberately public route.

export default sw.endpoint({ auth: 'none', handler: async () => ({ ok: true }) });

Declare application tables in db/schema.ts. Read them with sw.db.from for caller-scoped access or sw.db.server.from after authorizing the caller for server access. Write them with the corresponding structured methods, such as sw.db.server.insert. Raw query and batch use the separate raw SQL database on current projects.

Functions run directly on the platform with access to sw.db (database), sw.fs (file storage), sw.email (send email), sw.ai (AI models), sw.env (environment variables), sw.jobs (background jobs), sw.queue, and sw.logs. sw.db uses the function's authenticated project binding, so application code does not send a developer API key or construct a platform HTTP request. First-use activation, placement, transport, scheduling, and engine work can still contribute to latency. sw.db.batch([{sql, params}, ...]) runs multiple statements as one atomic transaction; any failure rolls every statement back. (ctx is an alias — same object, both names work.)

Source base (required on every live deploy). Pass base_release_id: the active_release_id from the project_export read your source came from, or null when the project has no source yet. The base is the one that came with the edited source; a newer id read just before deploying is not a valid base. A missing base returns 400 BASE_REQUIRED and nothing changes; a base that is no longer live returns 409 STALE_RELEASE_BASE with data.changed_files. Recovery is a re-export, the change re-applied to the new source, and a deploy with the new base. force:true deliberately replaces the live source; it still fails if another deploy lands while yours builds.

Projects without releases use base_version from your last deploy/export response instead. If the project changed elsewhere, deploy returns 409 STALE_BASE with data.changed_files, data.last_change_source, and data.last_change_at; review project_diff_versions before choosing force:true.

Version counter check (optional, separate from the source base). expected_version compares the project's deploy counter: a number returns 409 VERSION_CONFLICT with data.current_version when it differs; omitting it (or "latest") skips only this extra check. Omitting it never replaces base_release_id.

The success response always includes the new version. When available, it may also include _runtime_key_summary, a plain-language note on whether the runtime key for this deploy was narrowed to least-privilege scopes or fell back to blanket access.

Example:

{
  "project_id": "my-saas",
  "files": {
    "index.html": "<!DOCTYPE html><html><body><h1>Hello</h1></body></html>"
  },
  "functions": {
    "api/hello.ts": "export default sw.endpoint({ auth: 'none', handler: async () => ({ ok: true }) });"
  }
}

Handler code goes in functions; static assets (here, index.html) go in files.

The default workflow has one environment: read production source, check, deploy once, then verify the public production URL. somewhere preview is an optional advanced capability; preview inputs apply when a preview is explicitly requested and the account has hosted preview access (every plan includes it for signed-in accounts).

Inputs: project_id (required), draft, files, force, +18 more.

project_deploy_logA
Read-onlyIdempotent
Inspect

Get the build log for a deploy — the entry the bundler detected, every chunk it emitted with sizes, function bundle sizes, and any warnings. Compilation runs on the platform (you deploy raw source), so this is how you SEE what the build did — why CSS dropped, which chunk a warning came from — instead of reverse-engineering compiled output. Without version, it returns the latest deploy; a version from project_deploys returns a past one. Complements the build_log + rollback fields that project_deploy now returns inline.

Also surfaces failure context alongside (or instead of) a normal build log: last_failed_build (the most recent build that failed to compile), last_rejected (the most recent deploy rejected before compile, e.g. bundled-output detection), and recent_failures (up to 5 safe rows with failure_id, code, classification, message, remediation, known_cause, version, and at). somewhere api GET /v1/deploy/failure/<failure_id> resolves one exact reference. If the project has never had a successful deploy, version comes back null with an empty build_log and whatever failure context exists — that's the answer to "why did my first deploy fail," not an error.

Inputs: project_id (required), version, release_id.

project_deploysA
Read-onlyIdempotent
Inspect

List the recent deploy history for a project — successful deploys AND rejected/failed deploy attempts, interleaved by time (up to 150 successful releases plus 20 failed attempts). Each entry has a status field so you can tell a success from a rejection at a glance.

Example:

{ "project_id": "my-saas" }
// Returns: { "deploys": [
  { "status": "success", "version": 12, "promoted_at": "2026-04-20T...", "is_live": true, "commit_sha": "...", "deployed_by": { "user_id": "...", "email": "..." } },
  { "status": "rejected", "version": 11, "reason": "BUNDLED_DEPLOY_REJECTED", "message": "This looks like pre-built output...", "at": "2026-04-19T...", "is_live": false },
  { "status": "success", "version": 10, "promoted_at": "2026-04-18T...", "is_live": false }
] }

A rejected entry's version is the version it WOULD have become (may be null); it never went live. Each successful entry carries rollback_available, describing retained build availability. A false entry cannot be restored; true still requires schema-safe activation. project_rollback selects the previous activation; project_restore_version selects a retained version by number. Free covers the last 24 hours. Paid plans cover any retained version. Failure entries also include failure_id, a safe classification, and remediation. somewhere api GET /v1/deploy/failure/<failure_id> resolves one exact reference; the endpoint requires access to the owning project and never returns the private stack or provider diagnostic.

Each successful version shows its user-supplied note, if any, and the restore call when available. You can add a note when publishing or later. Each successful entry also carries build: { recorded: true, reported_cli_version, platform_version_id, platform_version_tag, runtime_build_version } — the CLI version the deploying client reported (its own claim, null when none was sent, e.g. an MCP deploy), the API build that published the release (the separate compiler build is not recorded), and the runtime build baked into its functions (null without functions). A release built without identity recording (including by older code during rollback) returns { recorded: false, reason: 'built_without_identity_recording' }; it is never guessed.

Inputs: project_id (required).

project_diff_versionsA
Read-onlyIdempotent
Inspect

Compare two preserved deploy versions of a project. Returns per-file added / removed / changed paths, plus truncated text previews for changed files. After a 409 VERSION_CONFLICT it shows what the other deployer shipped, ahead of merging and retrying.

Both versions must still exist in the preserved-snapshot window (the platform keeps the most recent 10 versions). project_deploys shows whether both numbers are available.

Example:

{ "project_id": "my-saas", "from": 46, "to": 47 }
// Returns: {
//   from: 46, to: 47,
//   added:   [{ path: "api/billing.ts", size: 1244 }],
//   removed: [],
//   changed: [{ path: "index.html", from_size: 980, to_size: 1102, from_preview: "<html>...", to_preview: "<html>..." }],
//   functions: { added: ["api/billing.ts"], removed: [], changed: [] },
//   functions_changed: true
// }

Inputs: to (required), from (required), project_id (required).

project_docsA
Read-onlyIdempotent
Inspect

Readable documentation for the deployed project. Returns deterministic docs generated from the exact deployed source, plus routes, symbols, data tables, dependency graph, coverage flags, and a Mermaid map. It is the starting read for an unfamiliar project.

By default the document describes the project's active release (a successful default answer carries version_source: 'active_release', release_id and source_manifest_hash); version selects an exact older one, which carries version_source: 'explicit' and no release metadata. The deterministic document is available shortly after a successful deploy. Docs are generated without a model call. Existing projects receive docs on their next deploy and are not backfilled.

Inputs: project_id (required), version.

project_exportA
Read-onlyIdempotent
Inspect

Pull the entire project in one call. Returns every deployed file — static HTML/CSS/JS as text, binary assets (images, fonts, favicons, .ico/.png/.woff*/etc) base64-encoded, server functions as source — keyed by path. This is the visual-editor fast path: one call → entire project → edit → project_deploy back.

For workflows like "redesign my homepage" or "swap the color scheme on the live site," this is the entry point. Pairs with project_deploy (full replacement) and project_patch (single-file update) on the write side.

Response shape: flat files: [{ path, type, content, encoding }] array with explicit per-entry type ("static" / "binary" / "function"), plus the same files as static_files / binary_files / functions maps. SVG is utf-8 text (it's XML); PNG / ICO / fonts / etc come back base64.

static_only: true returns only the visual layer (HTML / CSS / SVG / images / fonts) and not the server functions. Typical projects have 5–10× more function bytes than static bytes, so this is the right default for design / redesign / "swap the color scheme" workflows. The functions map comes back empty; static_files and binary_files are unchanged.

For one file (e.g. just CSS), project_file_read is lighter; for the tree alone (paths + sizes, no contents), project_files_list is much cheaper.

Example:

{ "project_id": "my-saas", "static_only": true }
// Returns: {
//   project_id: "my-saas-uuid", env: "prod", version: 47,
//   files: [
//     { path: "index.html",        type: "static",   content: "<!DOCTYPE...", encoding: "utf-8" },
//     { path: "logo.svg",          type: "static",   content: "<svg...",     encoding: "utf-8" },
//     { path: "hero.jpg",          type: "binary",   content: "<base64>",    encoding: "base64" }
//   ],
//   static_files: { ... }, binary_files: { ... }, functions: {},  // the same files as maps; functions empty when static_only
//   counts: { static_files: 8, binary_files: 2, functions: 0, total: 10 }
// }

Inputs: project_id (required), env, preview_id, static_only, +1 more.

project_file_readA
Read-onlyIdempotent
Inspect

Read the raw source of a single deployed file. Returns the actual bytes that were uploaded — not DOM-rendered HTML, not a screenshot. Static files come back as UTF-8 text; binary files (images, fonts, etc.) come back base64-encoded; server functions return their source code.

project_files_list lists available paths; project_export returns the full project.

Example:

{ "project_id": "my-saas", "path": "styles.css" }
// Returns: { project_id, env: "prod", path: "styles.css", type: "static", content: "body { ... }", encoding: "utf-8" }

Inputs: path (required), project_id (required), env, version, +2 more.

project_files_listA
Read-onlyIdempotent
Inspect

List every deployed file in the project — path, type (static/binary/function), size, last_modified. No file bytes. Cheap tree listing for "show me what's in there" before deciding what to pull.

project_file_read reads one file; project_export returns everything in one shot.

Example:

{ "project_id": "my-saas" }
// Returns: {
//   project_id: "my-saas-uuid", env: "prod",
//   files: [
//     { path: "index.html", type: "static", size: 4203, last_modified: "..." },
//     { path: "hero.jpg",   type: "binary", size: 82310, last_modified: "..." },
//     { path: "api/checkout.mjs", type: "function", size: 1244 }
//   ],
//   counts: { static: 8, binary: 2, functions: 5 }
// }

Inputs: project_id (required), env, preview_id, preview_session_id. Returns: ok, data, error, message

project_getA
Read-onlyIdempotent
Inspect

Project details, app info, project record, settings, metadata — fetch one project by id, subdomain, or "default". Returns the full project record. When the project's editors have saved context (see project_context), it is included as project_context: instructions, design principles and note topics, labelled as project data.

Example:

{ "project_id": "my-saas" }
// or
{ "project_id": "default" }

Inputs: project_id (required). Returns: ok, data, error, message

project_grepA
Read-onlyIdempotent
Inspect

Regex-search deployed authored source — every static source file and server function — and get back file:line matches in one call. The existing per-project call remains unchanged. Platform admins may instead pass scope:"live" (and omit project_id) to search every project currently serving production traffic (projects.status = 'deployed'). Release-pinned projects read their immutable release; other projects read their prod-slot authored source. Fleet responses report projects scanned/searched/skipped by reason, projects with no prod function script, and whether results were truncated. Every fleet hit carries the stable file/path/file_path, line/line_number, col/column, and text/matched_line compatibility fields.

pattern is a regular expression (not a literal substring). glob optionally scopes the search: a glob with no slash matches by filename (*.tsx → every .tsx file), one with a slash matches the path (api/** → just that folder).

Example:

{ "project_id": "my-saas", "pattern": "createClient\\(", "glob": "src/**" }
// Returns: {
//   project_id, env: "prod",
//   matches: [
//     { path: "src/lib/db.ts", line: 3, col: 18, text: "export const db = createClient(url, key)" }
//   ],
//   truncated: false, files_searched: 24
// }

Returns at most max_results matches (default 100, max 1000), capped per file too; truncated: true means a cap clipped the results — narrow the pattern or glob. Searches the live prod source by default. Explicit env: "dev" requires hosted preview access for signed-in accounts on every plan.

Inputs: pattern (required), env, glob, scope, +5 more.

project_listA
Read-onlyIdempotent
Inspect

My projects, my apps, my sites, my deployments, account inventory, dashboard overview — show every project I own or collaborate on. Each row includes is_owner so you can tell which is which.

Compact + paginated by default to keep the payload small: returns up to 50 projects with the core fields (id, name, subdomain, status, tags, created_at, last_deployed_at, latest_screenshot_url, favicon_url, is_owner). The render fields are included in this one response; screenshot/favicon URLs are null until their live-release asset exists. When more exist, the response ends with a note telling you the total and how to page. To narrow or expand: pass q (substring filter on name/subdomain), tag (organization label filter; multiple values combine with AND), limit/offset (paging), or fields:"full" for the complete record per row.

Example:

// project_list({ q: "saas", limit: 50 }) returns:
[
  { "id": "p_abc123", "name": "My SaaS", "subdomain": "my-saas", "status": "deployed", "last_deployed_at": "2026-04-01T...", "latest_screenshot_url": "https://api.somewhere.cloud/v1/deploy-screenshots/p_abc123/v7-desktop.png?exp=...&sig=...", "favicon_url": "https://my-saas.somewhere.site/favicon.ico", "tags": ["marketing"], "is_owner": true },
  { "id": "p_xyz789", "name": "Jen's App", "subdomain": "jen-app", "status": "draft", "last_deployed_at": null, "latest_screenshot_url": null, "favicon_url": null, "tags": [], "is_owner": false }
]

Shared projects: you can deploy, edit files, run db migrations, send email, and use AI — all billed to the project owner. You cannot delete, transfer, change env var values, or manage billing/spend caps on shared projects.

Inputs: q, tag, limit, fields, +1 more. Returns: ok, data, error, message

project_logsAInspect

Tail function logs, read recent runtime output, debug a just-deployed endpoint, see what console.log printed, observability. After every project_deploy / project_patch, it shows what the new code logged on the first few requests — no need to curl the endpoint and guess. Also writes logs (with a message).

Read mode (no message): returns the most recent log lines for the project, newest first. Filter by level, source (server | client | function | job | cron | queue | system | oauth), substring match, or trace ID. Default limit 50, max 500.

Write mode (with message): records a structured log line. Used by your own monitoring code, or by an agent that wants to mark a checkpoint. Writes are durable but ingested asynchronously — a line you just wrote may take a few seconds to appear in a read. queued:true confirms acceptance, not immediate readability.

Example:

// Read recent logs after a deploy:
{ "project_id": "my-saas", "limit": 50 }

// Read only errors:
{ "project_id": "my-saas", "level": "error", "limit": 50 }

// Read logs from one source:
{ "project_id": "my-saas", "source": "server", "search": "/api/checkout" }

// Write (with structured data):
{ "project_id": "my-saas", "message": "Payment processed", "level": "info", "data": "{\"amount\":49.99}" }

Inputs: project_id (required), data, level, limit, +4 more.

project_notice_acknowledgeA
Idempotent
Inspect

Mark a somewhere platform notice read or snooze its reminders for this maintainer. This only changes personal notice delivery; it never resolves the underlying project issue or grants any capability.

It takes the project_id and notice_id supplied with the notice. A snooze defaults to 24 hours and accepts 1–720 whole hours.

Inputs: action (required), notice_id (required), project_id (required), snooze_hours.

project_patchAInspect

Edit / change / update / modify / fix / tweak files in a deployed project — edit one or several deployed files in place with a find/replace, an ordered edits array of many find/replaces across files, a full-file rewrite, or a files map of several full-file writes in one atomic patch. Suited to visual-editor iteration and any quick code change. Unchanged files are preserved; only what you send is touched. Static changes reach production in ~1 second; function changes in 2–4 seconds.

For an existing project this touches only the files sent; project_deploy replaces the static file tree, so unchanged static files must be sent again. project_deploy is for the first deploy of a brand-new project.

The source comes from project_export. Its active_release_id is the base_release_id of the patch, including on dry runs. This required release anchor identifies the exact source you edited; base_version is an additional optional conflict check.

Three modes — same tool.

1. Find / replace (token-optimal, preferred for small edits): pass path + find + replace. The platform reads the current file, replaces every occurrence of find with replace, and writes it back. ~200 bytes on the wire instead of re-sending the whole file.

{ "project_id": "my-saas", "base_release_id": "<active_release_id from project_export>", "path": "index.html", "find": "<h1>Pricing</h1>", "replace": "<h1>Plans &amp; pricing</h1>" }

If find doesn't match the file, you get a 400 FIND_NOT_FOUND with a head/tail snippet. When a sufficiently similar region exists, data.closest_match also includes its offset, text and 0–1 confidence; unrelated text may have no close match. A corrected patch uses the exact text from a current project_export and that export's release anchor.

2. Ordered edits (many small changes in one patch): pass edits, an array of { "path", "find", "replace", "expect"? }, instead of top-level path/find/replace. Edits apply in order to the source of base_release_id (a later edit to the same file sees the earlier ones), across any number of files, and publish as ONE patch. If any edit does not match, nothing is published: the error is FIND_NOT_FOUND with zero-based data.edit_index. expect: n requires exactly n non-overlapping matches, else FIND_COUNT_MISMATCH with data.edit_index, data.path, data.expected and data.actual. At most 200 edits per call. A path is edited, written whole (files), or deleted (delete_files) in one patch, never two of these; other paths combine freely.

{ "project_id": "my-saas", "base_release_id": "<active_release_id from project_export>", "edits": [
  { "path": "src/App.tsx", "find": "const TITLE = 'Old'", "replace": "const TITLE = 'New'", "expect": 1 },
  { "path": "src/App.tsx", "find": "<Footer />", "replace": "<Footer year={2026} />" },
  { "path": "styles.css", "find": "color: red", "replace": "color: teal" }
] }

Unified diffs are not a patch format: ordered exact replacements plus whole-file files writes cover the same changes without a second parser. Whole local trees deploy with somewhere deploy; somewhere call project_patch --file args.json sends a large argument object from a file.

3. Full content (rewriting the file): pass path + content. The new bytes replace the file entirely.

{ "project_id": "my-saas", "base_release_id": "<active_release_id from project_export>", "path": "styles.css", "content": "body { background: black }" }

Path auto-routes: api/*, _lib/*, and root [id].ts paths go to functions; everything else (HTML, CSS, SVG, JSON, etc.) to static. Binary assets (images, fonts) use the matching binary surface — content and find/replace do not carry raw bytes.

Delete: delete_files is an array of paths. Works for static files and functions; missing paths are silently ignored. A rename or atomic replace combines one path + content write (or the one-entry files alias) with delete_files in the same call: the new file and removals publish as one patch transaction.

Conflict check (optional, recommended for shared projects): pass base_version from your last deploy/export response. If another deployer landed changes since, returns 409 STALE_BASE with data.changed_files, data.last_change_source, and data.last_change_at instead of overwriting. On STALE_BASE, project_diff_versions shows the change, and force:true overwrites the remote changes. The older expected_version strict CAS still works and returns VERSION_CONFLICT when the production version differs.

Preview first (optional): pass dry_run: true to get a per-file unified diff of what the patch WOULD change (data.diffs), plus added/modified/removed lists — nothing is written and the version doesn't change. The same call without dry_run applies it.

Safety net — what IS and is NOT checked. A patch that touches page-rendering files (HTML/JS/CSS) is blank-page health-checked after it goes live: if it blanked a previously-rendering page, the patch is automatically rolled back and you get a 400 DEPLOY_BLANK_PAGE with data.rolled_back. Pages that were already blank before the patch are never blocked.

A function-only patch (api/*, _lib/*, root [id].ts) is NOT blank-page-checked, and it does NOT get "the same protection as a full deploy." After a function patch the response carries a best-effort function_health field — { checked, status, ok } from one GET of a patched route. function_health.ok === false means the route returned a 5xx (e.g. a missing import → 500): your edit shipped but is broken in production. If function_health.checked === false the route couldn't be probed (no concrete route, browser unavailable) — it was NOT verified, so confirm it yourself. A clean build is NOT a working function; only function_health.ok === true (or your own request to the route) confirms it runs.

For a risky edit, dry_run:true and project_check come first, then one patch, verified on the public production URL. project_rollback restores the previous production version if needed.

Patches reach production immediately at https://{subdomain}.somewhere.site. The success response includes the new version, a next_step, function_errors (build failures) and, for function patches, function_health (runtime 5xx). Preview is advanced and must not be selected unless the user explicitly says the account is enabled.

Inputs: project_id (required), find, path, edits, +18 more.

project_restore_versionA
Idempotent
Inspect

Restore a specific past deploy version to be the live production version. Restoring by number leaves the database schema and data unchanged. project_deploys shows which versions are available: an entry with rollback_available: false is still in the history but its build is no longer restorable (the call is refused and nothing changes — deploying that version's source again brings it back). The currently live version is a no-op. Free can restore a retained deploy from the last 24 hours or roll back to the previous working version. Paid plans can restore any retained version.

Example:

{ "project_id": "my-saas", "version": 11 }

Inputs: version (required), project_id (required).

project_rollbackA
Idempotent
Inspect

Roll back the last deploy, on every plan. The code flips to the previous working version immediately: the version that was live just before the current one. By default this changes code without restoring data. Give a version number to restore a retained deploy from the last 24 hours on Free or any retained deploy on paid plans. Restoring by number leaves the database schema and data unchanged. If the project uses a managed database (db/schema.ts), the response also returns a schema plan in plain language — what the previous version expects of the database vs. what it looks like now — WITHOUT changing the schema. with_schema: true also rolls the schema back; it re-deploys the previous version's schema through the normal deploy path, so a column the new version added is refused (not silently dropped) and a column the old version still declares is restored from retention. Data is never touched beyond the retention/restore window. preview: true reviews before applying — it changes NOTHING and returns target_version (the version it would restore); that value as expected_target_version confirms it, and the rollback is refused (ROLLBACK_TARGET_CHANGED) if the live version moved since your preview, so the rollback never lands on a different version than the one you reviewed.

Inputs: project_id (required), preview, version, with_schema, +1 more.

project_screenshotsA
Read-onlyIdempotent
Inspect

Real picture of the deployed site for each recent version. The platform captures a desktop screenshot of the project's homepage after every deploy and stores it alongside the version history. Answers "what does this app look like right now" (e.g. for design / visual-editor workflows) and "did the last deploy change the way the homepage renders" (regression spot-check).

An optional version filters to a specific deploy.

By DEFAULT returns metadata only per screenshot (version, viewport, captured_at, size_bytes) — the large inline base64 image bytes are omitted to keep your context lean. include_data: true returns each as a data_url (data:image/png;base64,...) you can render with <img src={data_url}>; the browser tool sees and inspects the live page.

Example:

{ "project_id": "my-saas" }
// Returns (metadata only — data_url omitted by default):
{
  "project_id": "my-saas-uuid",
  "screenshots": [
    { "version": 12, "viewport": "desktop", "captured_at": "2026-05-19T...", "size_bytes": 142_321 },
    { "version": 11, "viewport": "desktop", "captured_at": "2026-05-18T...", "size_bytes": 138_004 }
  ]
}
// With include_data:true, each entry also contains: "data_url": "data:image/png;base64,..."

Inputs: project_id (required), version, include_data.

project_seo_checkA
Read-onlyIdempotent
Inspect

Inspect deployed SEO metadata from the active release's homepage HTML, robots.txt and sitemap.xml artifacts. Returns release identity, automatic fallback versus app-supplied provenance, metadata issues and advisory suggestions. This does not fetch the public site, execute JavaScript, crawl routes, edit source or verify indexing/ranking. Public HTTP/function responses and client-route coverage remain unobserved.

Inputs: project_id (required).

project_undeployA
DestructiveIdempotent
Inspect

Undeploy a project — revokes its public subdomain and returns it to an inactive state. All data is preserved.

Inputs: project_id (required).

project_view_urlsA
Read-onlyIdempotent
Inspect

Get the public live URLs for a project. prod is the verified custom domain when one exists; prod_fallback is the public *.somewhere.site URL and always serves the latest live deploy.

Example:

{ "project_id": "my-saas" }
// Returns: {
//   "prod": "https://app.yourcompany.com",          // null if no custom domain
//   "prod_fallback": "https://my-saas.somewhere.site",
//   "prod_version": 12,
//   "has_custom_domain": true
// }

Inputs: project_id (required). Returns: ok, data, error, message

push_sendAInspect

Need an alert to reach a user even when the app tab is closed? push_send sends a web push notification to one device, one app-user's devices, your developer devices, or the whole project.

Recipient targeting (exactly one; a missing, null or empty target is refused):

  • user_id: every device that signed-in app user registered.

  • subscription_id or endpoint: one device. Sending again sends another notification.

  • audience: 'developer': devices registered with push_subscribe.

  • audience: 'all': every device in the project (refused whole above 500).

payload may be a JSON object (recommended — your service worker parses it) or a string. Subscriptions that the push provider reports as gone (404/410) are auto-deleted. Inside a deployed function the equivalent call is sw.push.send({ payload, user_id }) — one object, payload nested; there is no second options argument.

Example:

{
  "project_id": "my-saas",
  "user_id": "u_alice",
  "payload": { "title": "New message", "body": "From Bob", "url": "/inbox/123" }
}
// Returns: { "sent": 1, "failed": 0, "gone": 0, "captured": 0, "recipients": 1, "history_recorded": true, "devices": [{ "subscription_id": "psub_...", "device_label": "Chrome on Android", "outcome": "sent", "http_status": 201, ... }] }

Inputs: payload (required), project_id (required), ttl, contact, +4 more.

run_codeAInspect

Run a short script once, server-side, against a project's own bindings — get the result + console logs back in one call. It replaces a throwaway debug endpoint or dozens of tool calls when inspecting data, trying a query variant, or running a one-off transformation.

code is an ES module whose default async function receives sw (the same database / files / search / ai bindings a deployed function gets) and returns a JSON-serializable value:

{
  "project_id": "my-saas",
  "code": "export default async function (sw) { const { data } = await sw.db.server.from('notes', { limit: 1 }); return data; }"
}

Declare application tables in db/schema.ts. Read them with sw.db.from for caller-scoped access or sw.db.server.from after authorizing the caller for server access. Write them with the corresponding structured methods, such as sw.db.server.insert. Raw query and batch use the separate raw SQL database on current projects. The script entry point above is for run_code. For a JSON route in api/, use export default sw.endpoint({ auth, handler }) and set auth explicitly. TypeScript infers the handler inputs and sw context. Use auth: 'none' only for a deliberately public route.

Runs with the project's OWN authority, not your developer key: no env secrets unless you pass include_env: true, no admin, no cross-project access, and outbound fetch is limited to public hosts. Returns { result, logs, duration_ms, error? }. result is capped at 256KB (truncated with a notice past that). logs keeps at most 100 entries. Each log message is cut at 64KB with a [truncated: …] marker at its end. All logs together stop at 4MB, followed by one final [logs truncated: …] entry. logs_truncated: true is set when entries were dropped by either limit (not when a single message is cut). error.message and error.stack are each cut at 64KB. A returned session over 64KB is not stored and the call answers SESSION_TOO_LARGE. timeout_ms defaults to 10000, max 30000.

Threading state across calls (opt-in): pass a stable session_id to carry explicit JSON state between runs. The saved JSON is exposed to your script as a read-only sw.session; a returned { session: {...} } object saves state for the next call (it is stored under that session_id, separately from result). Absent session_id = stateless, byte-identical to a normal run. This is explicit data you thread by id — NOT live-variable/closure persistence.

Inputs: code (required), project_id (required), args, session_id, +2 more.

search_index_listB
Read-onlyIdempotent
Inspect

List all search indexes for a project.

Inputs: project_id (required).

search_queryA
Read-onlyIdempotent
Inspect

Search an index. The default hybrid ranking fuses exact-keyword matching (typo-tolerant, great for SKUs, usernames, IDs, and any literal term) with meaning-based matching — so a document containing the query words ranks first, AND conceptually related documents are still found. Each result has its original content and metadata, a relevance score, a snippet that highlights the match (wrapped in …), and a signals breakdown of which signal(s) matched. offset pages through results — the response carries a page object with total and has_more.

Example:

{
  "project_id": "my-saas",
  "index": "help-articles",
  "query": "reset password",
  "limit": 5
}
// Returns: {
//   "results": [{ "id": "art-1", "content": "How to reset your password...", "metadata": { "category": "account" }, "score": 0.031, "snippet": "How to <mark>reset</mark> your <mark>password</mark>...", "signals": { "lexical": -3.1, "semantic": 0.92 } }, ...],
//   "page": { "offset": 0, "limit": 5, "total": 12, "has_more": true },
//   "mode": "hybrid"
// }

Inputs: index (required), query (required), project_id (required), mode, +2 more.

security_reviewA
Idempotent
Inspect

On-demand LLM security review of a project's deployed functions. Returns a structured Markdown report — findings (one per real risk), severity, and a fix.

Every plan can request a review. Paid plans get a longer report. Eligible paid plans also review when a preview is promoted. All plans use the same review model and minimal reasoning; only the report length limit differs.

Advisory only — never blocks anything. The deploy path never blocks on a pattern scan; it surfaces hits as warnings, and this tool is how you get the deep dive.

project_id is required (returns VALIDATION_ERROR if omitted). Backend failures are distinguishable, so a retry is never wasted on a persistent failure: a transient outage returns UPSTREAM_DOWN / UPSTREAM_RATE_LIMITED (retryable), while a persistent platform problem returns UPSTREAM_ERROR / CONFIG_ERROR (not retryable — a retry loop does not clear it).

Example:

{ "project_id": "my-saas" }
// Returns: { "findings": "## Findings\n### Auth bypass at api/checkout.ts ...\n...", "review_depth": "standard", "tier_unlocks_deep_review": false, ... }

Inputs: project_id (required), focus.

security_sitekeyA
Read-onlyIdempotent
Inspect

Get the CAPTCHA site key to embed in your frontend HTML. This is safe to expose publicly — it identifies the widget, not the user.

Example:

{}
// Returns: { "sitekey": "0x..." }

Usage in HTML:

<div class="cf-captcha" data-sitekey="0x..."></div>
<script src="https://your-captcha-provider.example/widget.js" async defer></script>

Inputs: no named parameters.

site_checkAInspect

Trigger an on-demand site check for a project. Usually returns the finished run with per-target details within ~10s; if probes are still executing it returns { run: { id, status: "running" } } — site_check_status has the result a moment later. It answers "is it back yet" after a fix, and serves as a post-deploy check.

Inputs: project_id (required).

site_check_statusA
Read-onlyIdempotent
Inspect

Get the latest smoke-test run for a project plus a short history. Smoke runs are auto-wired — homepage and any attached custom domains are probed every ~20 min and after every deploy. Status is "pass" / "fail" / "partial". Each run includes per-target details (URL, HTTP code, duration).

Inputs: project_id (required).

site_verifyAInspect

Runs one browser flow across desktop and phone viewports and returns one structured verdict: every named step, page/console/network health, expected request outcomes, both screenshot paths or URLs, and a non-blocking accessibility/layout line per viewport covering WCAG AA text contrast, horizontal overflow, and tap targets below the 24×24px WCAG 2.2 AA minimum (24–44px is listed as a note). Authenticated or seeded flows require project_id and a project-owned origin. An absent action list produces a load/health/two-screenshot check. Each viewport uses a fresh browser that closes inside the call, including on failure.

Inputs: url, auth, actions, cookies, +7 more.

support_ticketAInspect

Support tickets for the Somewhere platform team — submit, check, list, or resolve your own tickets. For reports about the platform itself: a doc gap, an unexpected error shape, a missing capability, a bug in an MCP tool, or an inconsistency between docs and behavior. Not for feedback on a user's own app — that's the feedback tool.

Four modes, by argument:

  • message → submits a new support ticket. Returns a durable ticket_id immediately, stores the raw ticket in the support inbox, and notifies the team. The team replies on that same ticket. When the team records a reply or resolves the ticket, the reporting developer receives an email and a developer-channel feedback_resolved event automatically. Ticket status remains readable before that notification arrives.

  • ticket_id and action: "resolve" → resolves a ticket the caller submitted. This cannot resolve another submitter's ticket. An authenticated platform admin may also pass response to write the customer-facing reply and resolve the ticket atomically.

  • ticket_id (no message) → reads that one ticket. Returns its status (open / investigating / resolved) and response (the team's reply, once written).

  • Neither → lists the tickets the caller submitted, most recent first (open and resolved), each with status, response, and resolution timestamp. A status filter narrows the list.

Example:

// Submit:
{
  "message": "PUT /v1/fs binary upload returns 200 but reads back as UTF-8-replaced bytes — every byte ≥0x80 becomes EF BF BD. Reproed with curl --data-binary @cat.jpg.",
  "context": { "endpoint": "PUT /v1/fs", "file_size": 82823, "tried": ["binary_files base64 (worked)"] }
}

// Check one ticket:
{ "ticket_id": "pfb_a1b2c3d4e5f6" }

// Resolve your own ticket:
{ "ticket_id": "pfb_a1b2c3d4e5f6", "action": "resolve" }

// Admin reply + resolve:
{ "ticket_id": "pfb_a1b2c3d4e5f6", "action": "resolve", "response": "This is fixed and live. No action needed." }

// List open tickets:
{ "status": "open", "limit": 20 }

Inputs: limit, action, status, context, +5 more.

tasks_createBInspect

Create a task in a project. Tasks are per-project tickets — useful for bugs, todos, or end-user-filed feedback inside your app. Tasks live in the project's own database.

Example:

{
  "project_id": "my-saas",
  "title": "Fix login redirect",
  "description": "After OAuth, users land on /home instead of /dashboard.",
  "priority": "high",
  "labels": ["bug", "auth"]
}

Inputs: title (required), project_id (required), area, type, +12 more.

tasks_getA
Read-onlyIdempotent
Inspect

Read current task state by default, bounded to about 12,000 JSON characters, with history counts and expansion instructions. view=relationships pages explicit links and parent/replacement-field links, current target state and supersession pointers; task_id leads to the target. Missing targets and partial pointers are explicit. view=history pages comments, activity, guidance revisions or review records (kind), newest first with stable ID ties; default 5. view=field expands an omitted top-level field as bounded JSON-text chunks; a history field also takes kind and event_id. The same read options with next_cursor as cursor continue. History uses a keyset and initial rowid/time upper bounds; appends do not restart it, deletions disappear, and edited bodies are live. Membership is not frozen: deletion followed by a same-timestamp insert can admit a new event on a later page. Field chunks reject changed content with CURSOR_STALE; a new field read returns the current content. view=full explicitly requests the unbounded compatibility response with all comments/activity ordered oldest first (created_at ASC, id ASC). Prefix task IDs work when unique.

Inputs: task_id (required), project_id (required), kind, view, +5 more.

tasks_listA
Read-onlyIdempotent
Inspect

Read tasks. view=board returns a board scan: 50 concise current-state rows by default, no descriptions/comments. Other reads default to a small task page (10, bounded response). The same filters with page.next_cursor as cursor continue; pages are not concatenated automatically. Task ordering is live keyset: edits to sort/filter fields may skip or repeat rows; a new read starts a fresh queue. Fields in omitted are partial; tasks_get view=field expands them. detail=full explicitly permits unbounded descriptions. task_id reads one current task; tasks_get covers history/field options. review_for_closure reports its source candidate limit. tasks_overview covers project direction and work; tasks_summary gives counts and memory_search durable guidance.

Inputs: project_id (required), q, area, kind, +20 more.

tasks_overviewA
Read-onlyIdempotent
Inspect

Start with a bounded project brief: vision, SOPs, recorded priorities, work underway, blockers and completed work with release links. Uses existing records, no model ranking. Two records per section; a focused section returns up to five. Counts, ordering and continuation are explicit. Reviewed guidance is distinguished from newer drafts. Excerpts are partial; tasks_get has the source and linked guidance. Closed tasks without a release link are not presented as shipped.

Inputs: project_id (required), area, cursor, section.

tasks_reconcileA
Read-only
Inspect

Reconcile Board proposal pass for Task OS. Scans active tasks, runs objective drift rules plus a bounded cheap classification pass, and returns proposed relationship/status/assignment/duplicate corrections. Proposal-only: applied is always false and this tool never changes tasks or edges. Review proposals and apply selected changes with tasks_update.

Inputs: project_id (required).

tasks_summaryA
Read-onlyIdempotent
Inspect

At-a-glance ticket counts for a project with ZERO rows returned — total plus counts grouped by status, priority, area, and assignee, plus a stale count (in_progress tasks untouched beyond stale_days). It returns a dashboard number ("urgent: 3, high: 28, blocked: 5") instead of listing every task; it scales to thousands of tickets. tasks_list returns the rows themselves.

Inputs: project_id (required), stale_days.

tasks_updateAInspect

Update a task's fields, append a comment, or upload and attach authorized file references. comment adds a comment without changing other fields. Status transitions to 'done' automatically stamp completed_at. Closing a task (status: 'done') takes a resolution_note — it's persisted as a comment AND included in the resolution email/webhook so the reporter knows what was done. Omitting it when transitioning to done returns a non-blocking suggestions entry asking for a resolution note.

Progress belongs in status_note (and health), not a comment per step. The three fields have distinct jobs: description is the living document (intent and contract, rewritten as the truth changes), status_note is the current state (overwritten each update, so one read tells you where things stand), and comments are append-only EVIDENCE — commit hashes, verification output, links. Appending status as comments is what makes a long-lived task unreadable: the thread renders oldest-first, so a reader meets the superseded version before the live one. Overwriting status_note loses nothing; the old value is kept in the activity log.

Inputs: task_id (required), project_id (required), area, type, +24 more.

usage_summaryA
Read-onlyIdempotent
Inspect

Get account usage totals, owned-project count, limits, and aggregate database/file storage with no arguments. Project AI calls and costs exclude Advisor calls, which are accounted separately. From this change onward, new release-based production publications count once on successful completion, excluding previews, dry runs, unchanged deploys, rollbacks and retries. Historical counters retain their original meaning.

view: "projects" returns a bounded page of owned-project details (default 20, maximum 100); the returned cursor fetches the next page. Account totals remain account-wide. Passing project_id or period uses the historical usage call (deploys, project AI calls/costs, emails), without storage or pagination.

Inputs: view, limit, cursor, period, +1 more.

web_scrapeAInspect

Fetch a public web page and return its content as clean markdown (default), with optional html, raw_html, links, and screenshot. Strips nav/footer/sidebar by default so you get the main article body.

It reads pages that are not otherwise locally accessible — docs, blog posts, marketing pages, articles. The response is page metadata (title, description, language) plus the requested formats. If the page served a bot-challenge interstitial ("verify you are human") instead of real content, the response carries challenge_detected: true — that content is not the page, and an immediate retry usually returns the same challenge.

Screenshot format (formats: ["screenshot"]) uses the same three-tier answer as browser: small enough (auto-downscaled) → inline data:image/...;base64,...; too large with no storage → a short-TTL scratch_url you don't have to clean up; storage: "/path.jpg" set → written permanently to project files, returned as { storage_path, size_bytes }.

Example:

{ "project_id": "my-saas", "url": "https://somewhere.cloud/docs/getting-started.txt" }
// Returns: { "url": "...", "title": "Start an app", "markdown": "# Start an app\n...", "status_code": 200 }
{ "project_id": "my-saas", "url": "https://example.com", "formats": ["markdown", "links"], "only_main": false }
{ "project_id": "my-saas", "url": "https://example.com", "formats": ["screenshot"], "storage": "/scratch/hero.jpg" }

Inputs: url (required), project_id (required), formats, storage, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to build and deploy an app from a GitHub repository to a managed live server and then operate it — logs, captured errors, health checks, managed Postgres, secrets, custom domains, email authentication, and Stripe checkout links. It also exposes safe, read/write-labelled tools so agents can rebuild, start/stop, and inspect projects without ever editing source code.
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Deploy internal apps built with AI behind your company login, each with its own database, file storage and secrets. Tools to deploy, read live logs, set who can open an app, assign roles and save secrets.
      12
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Self-hosted Docker sandboxes for coding agents: create a sandbox with its own Docker daemon, deploy a docker-compose stack into it, read and write its files, and get a URL for every app. Tokens can be limited to one sandbox.
      38
      6
      AGPL 3.0
    Try in Browser

    Glama MCP Gateway

    Add one secure layer between your agents and this server.

    Resources