mcp

Start MCP servers in a sandbox and get the URLs your agent connects to.

Starts the gateway in the sandbox and answers once it listens: each server has a Streamable HTTP URL, and every request needs the Authorization header returned. Servers install in the background (npm, uv or a pinned release, checked against its SHA-256) and report installing, then ready; poll GET .../mcp. They run as the sandbox's user behind its own network rules, which this never changes: a host the rules refuse is a warning. Needs exec.

post/v1/sandboxes/{id}/mcp

Request

  • Base URL: https://api.withruntime.com
  • URL: https://api.withruntime.com/v1/sandboxes/{id}/mcp
  • Auth: HTTP bearer

Path parameters

idstring required

Resource identifier (UUID).

Headers

Idempotency-Keystring

Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header.

Request body

portinteger

The gateway's port in the sandbox. Default 8765.

replaceboolean

Stop a gateway already running and start this one.

publicboolean

Serve the gateway at a public preview: URLs with no link token that never expire, for an agent to be configured with once. The Authorization header still guards every request, and it is kept across starts (after a restart, or with replace) until DELETE .../mcp. Needs an account with a kept top-up, as any public preview.

Response

Success

runningboolean required
portinteger nullable
publicboolean

The URLs are a public preview: no link token, no expiry.

tokenstring

Send it as Authorization: Bearer <token>.

headersobject

The headers every MCP request needs.

urlExpiresAtstring nullable

When the URLs' link token expires; read again for new ones. null for public URLs, which do not expire.

warningsstring[]

Changes

No recorded changes to this operation across all 1 revision of this API.