MCP tools

The server is at https://api.briq.cloud/mcp. Tools mirror the REST API. Every result about a briq ends with its cost line:

bq_7kq2m9x1p4ab db (postgres:16) running · …internal · cost so far … · sleeps at 18:42 UTC unless used

briq_run

Create and start a briq from a recipe or an image. Returns once it is ready: its healthcheck passes, or without one its process has started.

With recipe, the image-only fields are refused: pass them in params, as the recipe's cookbook page lists them.

Output: the briqs (id, state, host, endpoints), the outputs (a recipe's connection strings, secrets briq generated, URL), the cost line. A secret you passed in is not printed back.

briq_run({ recipe: "postgres", params: { version: "16" } })
→ bq_7kq2m9x1p4ab db (postgres:16) running · …internal · cost so far … · sleeps at 18:42 UTC unless used
  outputs:
    DATABASE_URL=postgres://postgres:…@…internal:5432/app

briq_exec

Run a command in a briq. Input: { briq, cmd: string[], timeoutMs?, stdin? }. cmd is an argv run without a shell: ["psql", "-c", "select 1"], not ["psql -c 'select 1'"] (that looks for a program named after the whole line, and fails with exit 127); for pipes, globs, && or $VARS, pass ["sh", "-c", "…"]. timeoutMs 60000 by default, at most 600000; keep the command under about 16 KB and send bigger input as stdin. Output: exit code, stdout and stderr (stdout truncated at 32 KB). A sleeping briq is woken first, so the call is slower. On a stopped briq, an error that says why: invalid_state (409) after a stop or an exit (with the code), quota_exceeded or payment_required (402) while a limit holds.

briq_exec({ briq: "bq_7kq2m9x1p4ab", cmd: ["psql", "-U", "postgres", "-c", "select count(*) from orders"] })
→ exit 0
  count
  -----
  1284
  cost so far … · sleeps at 18:42 UTC unless used

briq_logs

Input: { briq, since?, limit? } (since is the next cursor of a previous call, limit up to 1000). Output: log lines and next.

briq_files_put / briq_files_get

Write or read one file, base64, up to 1 MB each way. Input: { briq, path, contentBase64 } / { briq, path }. A larger file is refused with a validation error that says so, in both directions: move it from inside the briq instead (git clone, curl), or read part of it with briq_exec. A 1 MB write takes up to half a minute. Writing one of the briq's boot files answers with a warning: the spec writes it again at the next start.

A write answers with the file's sha256, and verified: true when the briq computed the same digest from its disk (its image has sha256sum): compare it with your copy's. Line breaks in the base64 are ignored; base64 whose length shows it was cut short is refused with a validation error, rather than written and found broken later.

briq_files_put({ briq: "bq_7kq2m9x1p4ab", path: "/seed.sql", contentBase64: "aW5zZXJ0…" })
briq_exec({ briq: "bq_7kq2m9x1p4ab", cmd: ["psql", "-U", "postgres", "-f", "/seed.sql"] })

briq_expose

Give the briq its HTTPS URL, on one port, or a TCP endpoint. Input: { briq, port, protocol?, mode?, rotate? }. mode is private, a URL only whoever has it can open (it carries a secret checked before any request reaches the briq), or public, open to anyone. Without mode, a URL the briq already has keeps its mode, and a first URL is public.

• A briq has one URL. Its front door (the recipe's, or a briq's only port) publishes at once. Another port moves the URL there and restarts the machine: the processes start over, files on disk are kept, and the result carries a note saying so.
• rotate: true gives a private URL a new token: the URL stays, links and cookies with the old token stop working. A public URL has none to rotate.
• A briq declares at most 32 ports; exposing a new one past that is refused.
• protocol is http by default. A database protocol (postgres, mysql, redis, mongodb, amqp, bolt, grpc) makes a TCP endpoint: reachable from outside over TLS, for any briq. A recipe's database port refuses http and names its protocol. mode does not apply: the password is the gate. See Connect to a database from outside.

See Expose a preview URL.

briq_expose({ briq: "bq_9a2fk3m8q1zt", port: 3000, mode: "private" })
→ exposed port 3000 (private): https://api-k7x3.briq.run/?briq_token=…

briq_fork

Copy a briq, or a whole stack, before a change you might want to undo. See Forks.

Output: the forks, what each copied (disk or config), outputs pointing at the forks, the cost line.

briq_stop / briq_start / briq_destroy

Input: { briq }. Stop keeps the disk, volume and every other file; destroy removes it. Each returns once the move lands (up to 30 s); a stopping, starting or destroying state means it is still on its way, and calling again is safe. A briq stopped by briq_stop or its own exit stays stopped until briq_start. One stopped by a limit sleeps once the limit clears. A sleeping one needs neither: the next call or visit wakes it.

briq_set_sleep

Change when a briq goes to sleep. Input: { briq, sleep, stack? }: sleep as in briq_run, stack: true for every briq of its stack. A running briq sleeps the new window from now; a sleeping one keeps sleeping until its next use. Not needed for ordinary work: every call and every visit already pushes the sleep back.

briq_set_sleep({ briq: "bq_7kq2m9x1p4ab", sleep: "3h" })
→ bq_7kq2m9x1p4ab db (postgres:16) running · …internal · cost so far … · sleeps at 21:12 UTC unless used

briq_list / briq_status

Input: { stack?, all? } / { briq }. Output: state (running, sleeping, stopped…), image, host, cost and when it sleeps per briq; for one, also why it stopped (stoppedReason), its last process exit (lastExit), endpoints, env (secrets masked) and boot files (path and size).

briq_quota

Input: {}. Output: spend today against the daily cap, credits left, live briqs and how many more are allowed, allowed sizes, the longest sleep. The spend and the live briqs that count toward the limit are this credential's own: an agent that signed in again has a new one, so briqs it started before show in the team's count (teamLiveBriqs) and in briq_list, not in its own.

briq_catalog

Input: { name? }. Output: every recipe with a one-line description; with name, every parameter it takes (type, default, what it does), its outputs and briqs.

briq_docs

Input: { page? }. Without page, the index of every docs, cookbook and legal page (/llms.txt); with it, that page as Markdown: concepts/fork, cookbook/postgres, legal/dpa.

briq_feedback

Input: { topic: "bug" | "idea" | "question", message }. Emails the people who build briq. For when briq does not do what these docs say, an error has no explanation (a 5xx), the docs miss something, or there is an idea. The answer goes by email to the person who connected the agent (or the team's owner), who also gets a copy; the team's audit log records it as support.send. Output: the request id to quote, and who will get the answer. Five per ten minutes.

Resources and prompts

• briq://recipes/<name>: a recipe's parameters, outputs and briqs.
• briq://docs/<page>: every page briq_docs can read.
• Prompt briq_getting_started: how to use the tools well (prefer recipes, reuse a stack, read the cost line, destroy what you created).

Transport and auth

Streamable HTTP, stateless. Authentication follows the MCP authorization spec: a request without credentials gets 401 with WWW-Authenticate pointing at https://api.briq.cloud/.well-known/oauth-protected-resource/mcp. The authorization server (https://app.briq.cloud/api/auth) supports Client ID Metadata Documents, dynamic client registration, PKCE (S256) and the briq and offline_access scopes. Access tokens last 30 days; refresh tokens 30 days from their last use, and each one works once. A client that signs in with a device code (RFC 8628) gets a refresh token too, whatever scopes it asked for; a code request that names no scope gets the ones the client registered. The code waits 15 minutes for approval. A sign-in request refused for coming too often (429) says how long to wait: Retry-After, and retry_after_seconds in the body. An API key (Authorization: Bearer bq_live_…) works too.