Spaces transport (TypeScript)

MCP-over-HTTP and Tauri transports for Spaces in webviews and browsers.

Import from @trycua/cua/spaces/transport. This page covers the hand-written TypeScript layer; the generated native binding (sandboxes, guest, fleet, spaces objects) is documented per object in the Cua SDK reference.

Classes#

McpHttpTransport#

The one interface a host has to implement.

Implementations must:

resolve the reply whose id matches the request's, and not some other reply that happened to arrive first;
resolve null for a notification;
reject every in-flight call if the peer dies, rather than leaving callers hanging on a reply that is never coming;
be safe to call again after close(), either by restarting or by rejecting clearly.

Implements#

Transport

Constructors#

Constructor

new McpHttpTransport(options): McpHttpTransport;

Parameters

Parameter	Type
`options`	`McpHttpOptions`

Returns

McpHttpTransport

Properties#

Property	Modifier	Type	Default value	Description
`kind`	`readonly`	`"http"`	`"http"`	A short name for diagnostics: `"stdio"`, `"tauri"`.

Accessors#

sessionId

Get Signature

get sessionId(): string | undefined;

The session id the daemon minted, once initialized.

Returns

string | undefined

Methods#

close()

close(): Promise<void>;

Ends the MCP session (DELETE /mcp). Never throws.

Returns

Promise<void>

Implementation of

Transport.close

send()

send(message, options?): Promise<RpcResponse | null>;

Send one message; resolve its reply, or null for a notification.

Parameters

Parameter	Type
`message`	`RpcOutgoing`
`options`	`SendOptions`

Returns

Promise<RpcResponse | null>

Implementation of

Transport.send

McpSession#

Constructors#

Constructor

new McpSession(transport, options?): McpSession;

Parameters

Parameter	Type
`transport`	`Transport`
`options`	`SessionOptions`

Returns

McpSession

Properties#

Property	Modifier	Type
`transport`	`readonly`	`Transport`

Methods#

call()

call(
   name,
   args?,
   options?
): Promise<ContentPart[]>;

Call a tool, throwing ToolError if it failed.

Parameters

Parameter	Type
`name`	`string`
`args`	`Record`<`string`, `Json`>
`options?`	`SendOptions`

Returns

Promise<ContentPart[]>

callJson()

callJson<T>(
   name,
   args?,
   options?
): Promise<T>;

Call a tool whose text part is JSON, and parse it.

Worth its own method because the parse failure needs to say which tool produced the unparsable text: without that, a server-side format change surfaces as a bare SyntaxError with no attribution.

Type Parameters

Type Parameter	Default type
`T`	`Json`

Parameters

Parameter	Type
`name`	`string`
`args`	`Record`<`string`, `Json`>
`options?`	`SendOptions`

Returns

Promise<T>

callRaw()

callRaw(
   name,
   args?,
   options?
): Promise<ToolResult>;

Call a tool and return its envelope, including a failure.

Use this when a caller wants to inspect isError itself: for instance a probe that treats "not available" as an answer rather than an exception. Most callers want call.

Parameters

Parameter	Type
`name`	`string`
`args`	`Record`<`string`, `Json`>
`options?`	`SendOptions`

Returns

Promise<ToolResult>

callText()

callText(
   name,
   args?,
   options?
): Promise<string>;

Call a tool and return its text parts joined: the common case, since most of these tools answer with one text part.

Parameters

Parameter	Type
`name`	`string`
`args`	`Record`<`string`, `Json`>
`options?`	`SendOptions`

Returns

Promise<string>

close()

close(): Promise<void>;

Returns

Promise<void>

initialize()

initialize(options?): Promise<ServerInfo | undefined>;

Perform the MCP handshake, at most once per session.

The server does not require this: it builds its dispatch table before the read loop starts, so tools/call works cold. We do it anyway, and we memoize it: it is what makes this session usable against a conforming MCP server rather than only against this one, and the cost is a single round trip.

The result is cached as a promise, not a value, so concurrent first calls share one handshake instead of racing two.

Parameters

Parameter	Type
`options?`	`SendOptions`

Returns

Promise<ServerInfo | undefined>

listTools()

listTools(options?): Promise<ToolDescriptor[]>;

Every tool the server serves, with its input schema.

Parameters

Parameter	Type
`options?`	`SendOptions`

Returns

Promise<ToolDescriptor[]>

TauriTransport#

The one interface a host has to implement.

Implementations must:

resolve the reply whose id matches the request's, and not some other reply that happened to arrive first;
resolve null for a notification;
reject every in-flight call if the peer dies, rather than leaving callers hanging on a reply that is never coming;
be safe to call again after close(), either by restarting or by rejecting clearly.

Implements#

Transport

Constructors#

Constructor

new TauriTransport(options): TauriTransport;

Parameters

Parameter	Type
`options`	`TauriOptions`

Returns

TauriTransport

Properties#

Property	Modifier	Type	Default value	Description
`kind`	`readonly`	`"tauri"`	`"tauri"`	A short name for diagnostics: `"stdio"`, `"tauri"`.

Methods#

close()

close(): Promise<void>;

Ask the bridge to close the server's stdin.

A failure here is swallowed: the transport is being torn down, the app may already be quitting, and turning "could not reach the bridge while closing" into an exception makes shutdown paths fragile for no gain.

Returns

Promise<void>

Implementation of

Transport.close

send()

send(message, options?): Promise<RpcResponse | null>;

Send one message; resolve its reply, or null for a notification.

Parameters

Parameter	Type
`message`	`RpcOutgoing`
`options`	`SendOptions`

Returns

Promise<RpcResponse | null>

Implementation of

Transport.send

ToolError#

A tool that ran and failed.

This is a separate type from TransportError on purpose. The server reports a failing tool as a successful JSON-RPC response carrying isError: true; the only JSON-RPC error objects it ever sends are -32601 for an unknown method or tool. Collapsing the two would make "the sandbox refused this command" indistinguishable from "the control plane is not running", and those need different handling by every caller.

Extends#

Error

Constructors#

Constructor

new ToolError(
   tool,
   content,
   structured?
): ToolError;

Parameters

Parameter	Type
`tool`	`string`
`content`	`ContentPart`[]
`structured?`	`Json`

Returns

ToolError

Overrides

Error.constructor

Properties#

Property	Modifier	Type	Default value	Description
`content`	`readonly`	`ContentPart`[]	`undefined`	-
`kind`	`readonly`	`string` \| `undefined`	`undefined`	The server's stable error kind (`capability_missing`, `teleport_refused`, `not_found`, ...), when it sent one.
`tag`	`readonly`	`"ToolError"`	`"ToolError"`	-
`tool`	`readonly`	`string`	`undefined`	-

TransportError#

Thrown for anything that goes wrong beneath the tool call: a dead peer, a timeout, a JSON-RPC error object. A failing tool is not this: see ToolError, because this server reports tool failure as a successful response carrying isError: true.

Extends#

Error

Constructors#

Constructor

new TransportError(message, code?): TransportError;

Parameters

Parameter	Type
`message`	`string`
`code?`	`number`

Returns

TransportError

Overrides

Error.constructor

Properties#

Property	Modifier	Type	Default value
`code`	`readonly`	`number` \| `undefined`	`undefined`
`tag`	`readonly`	`"TransportError"`	`"TransportError"`

Interfaces#

ClientInfo#

Properties#

Property	Type
`name`	`string`
`version`	`string`

ContentPart#

One part of a tool result. call_tool passes through image, audio and resource parts from an in-space tool unchanged, so this is not only ever text.

Indexable#

[key: string]: Json | undefined

Properties#

Property	Type
`text?`	`string`
`type`	`string`

McpHttpOptions#

Properties#

Property	Type	Description
`fetch?`	`FetchFn`	Inject a fetch (tests, a Tauri HTTP plugin). Defaults to `globalThis.fetch`.
`token?`	`string`	The daemon's loopback bearer token.
`url`	`string`	Daemon loopback base URL (`http://127.0.0.1:<port>`) or the full `/mcp` URL.

RpcError#

@trycua/cua/spaces/transport: the Spaces control plane for hosts that cannot load the native binding (a Tauri webview, a browser).

Dependency-free TypeScript: McpSession speaks MCP to the Rust Spaces server over any Transport:

McpHttpTransport: the cua daemon loopback /mcp (streamable HTTP, bearer = the daemon's loopback token);
TauriTransport: invoke() into the Tauri app's Rust side.

Node code should use @trycua/cua/spaces (the typed SDK) instead. See types.ts for why the seam exchanges whole JSON-RPC messages rather than bytes.

Properties#

Property	Type
`code`	`number`
`data?`	`Json`
`message`	`string`

RpcNotification#

A message with no id. It gets no reply, and a transport must resolve null for it rather than inventing one.

Properties#

Property	Type
`jsonrpc`	`"2.0"`
`method`	`string`
`params?`	`Json`

RpcRequest#

@trycua/cua/spaces/transport: the Spaces control plane for hosts that cannot load the native binding (a Tauri webview, a browser).

Dependency-free TypeScript: McpSession speaks MCP to the Rust Spaces server over any Transport:

McpHttpTransport: the cua daemon loopback /mcp (streamable HTTP, bearer = the daemon's loopback token);
TauriTransport: invoke() into the Tauri app's Rust side.

Node code should use @trycua/cua/spaces (the typed SDK) instead. See types.ts for why the seam exchanges whole JSON-RPC messages rather than bytes.

Properties#

Property	Type
`id`	`RpcId`
`jsonrpc`	`"2.0"`
`method`	`string`
`params?`	`Json`

RpcResponse#

@trycua/cua/spaces/transport: the Spaces control plane for hosts that cannot load the native binding (a Tauri webview, a browser).

Dependency-free TypeScript: McpSession speaks MCP to the Rust Spaces server over any Transport:

McpHttpTransport: the cua daemon loopback /mcp (streamable HTTP, bearer = the daemon's loopback token);
TauriTransport: invoke() into the Tauri app's Rust side.

Node code should use @trycua/cua/spaces (the typed SDK) instead. See types.ts for why the seam exchanges whole JSON-RPC messages rather than bytes.

Properties#

Property	Type
`error?`	`RpcError`
`id`	`RpcId`
`jsonrpc`	`"2.0"`
`result?`	`Json`

SendOptions#

@trycua/cua/spaces/transport: the Spaces control plane for hosts that cannot load the native binding (a Tauri webview, a browser).

Dependency-free TypeScript: McpSession speaks MCP to the Rust Spaces server over any Transport:

McpHttpTransport: the cua daemon loopback /mcp (streamable HTTP, bearer = the daemon's loopback token);
TauriTransport: invoke() into the Tauri app's Rust side.

Node code should use @trycua/cua/spaces (the typed SDK) instead. See types.ts for why the seam exchanges whole JSON-RPC messages rather than bytes.

Properties#

Property	Type	Description
`signal?`	`AbortSignal`	Aborts the wait. A transport should still expect the server to finish the work: this server has no `notifications/cancelled` handling, so aborting abandons the reply rather than stopping the call.
`timeoutSeconds?`	`number`	Seconds to wait for a reply. The default is deliberately long. `teleport_app` and provisioning run with `timeout=900` server-side, and the agent-CLI registration this server ships with sets `requestTimeoutMs: 900000`. A transport that imposed a short deadline would silently break the app's slowest and most valuable operations, so a conformer must not shorten this on its own initiative.

ServerInfo#

Properties#

Property	Type
`name`	`string`
`version`	`string`

SessionOptions#

Properties#

Property	Type
`clientInfo?`	`ClientInfo`

TauriOptions#

Properties#

Property	Type	Description
`invoke`	`InvokeFn`	Usually `(await import("@tauri-apps/api/core")).invoke`.
`requestCommand?`	`string`	The Rust command name (default `spaces_mcp_request`).
`shutdownCommand?`	`string`	The Rust command that ends the session (default `spaces_mcp_shutdown`).

ToolDescriptor#

Properties#

Property	Type
`description?`	`string`
`inputSchema?`	`Json`
`name`	`string`

ToolResult#

Properties#

Property	Type	Description
`content`	`ContentPart`[]	-
`isError`	`boolean`	-
`structured?`	`Json`	`structuredContent`, when the tool returned one (tool errors carry `{error: {kind, message}}` with a stable `kind`).

Transport#

The one interface a host has to implement.

Implementations must:

resolve the reply whose id matches the request's, and not some other reply that happened to arrive first;
resolve null for a notification;
reject every in-flight call if the peer dies, rather than leaving callers hanging on a reply that is never coming;
be safe to call again after close(), either by restarting or by rejecting clearly.

Properties#

Property	Modifier	Type	Description
`kind`	`readonly`	`string`	A short name for diagnostics: `"stdio"`, `"tauri"`.

Methods#

close()

close(): Promise<void>;

Release the peer. Idempotent.

Returns

Promise<void>

send()

send(message, options?): Promise<RpcResponse | null>;

Send one message; resolve its reply, or null for a notification.

Parameters

Parameter	Type
`message`	`RpcOutgoing`
`options?`	`SendOptions`

Returns

Promise<RpcResponse | null>

Type Aliases#

FetchFn#

type FetchFn = (input, init) => Promise<{
  headers: {
     get: string | null;
  };
  ok: boolean;
  status: number;
  text: Promise<string>;
}>;

The fetch shape this needs (the global one, or an injected fake).

Parameters#

Parameter	Type
`input`	`string`
`init`	{ `body?`: `string`; `headers`: `Record`<`string`, `string`>; `method`: `string`; `signal?`: `AbortSignal`; }
`init.body?`	`string`
`init.headers`	`Record`<`string`, `string`>
`init.method`	`string`
`init.signal?`	`AbortSignal`

Returns#

Promise<{ headers: { get: string | null; }; ok: boolean; status: number; text: Promise<string>; }>

InvokeFn#

type InvokeFn = <T>(command, args?) => Promise<T>;

The shape of Tauri's invoke, narrowed to what this needs.

Type Parameters#

Type Parameter
`T`

Parameters#

Parameter	Type
`command`	`string`
`args?`	`Record`<`string`, `unknown`>

Returns#

Promise<T>

Json#

type Json =
  | null
  | boolean
  | number
  | string
  | Json[]
  | {
[key: string]: Json;
};

A JSON value, as it crosses the wire.

RpcId#

type RpcId = number | string;

JSON-RPC 2.0 ids: this SDK only ever sends numbers, but a reply echoes whatever it was given, and a conforming peer may use a string.

RpcOutgoing#

type RpcOutgoing = RpcRequest | RpcNotification;

@trycua/cua/spaces/transport: the Spaces control plane for hosts that cannot load the native binding (a Tauri webview, a browser).

Dependency-free TypeScript: McpSession speaks MCP to the Rust Spaces server over any Transport:

McpHttpTransport: the cua daemon loopback /mcp (streamable HTTP, bearer = the daemon's loopback token);
TauriTransport: invoke() into the Tauri app's Rust side.

Node code should use @trycua/cua/spaces (the typed SDK) instead. See types.ts for why the seam exchanges whole JSON-RPC messages rather than bytes.

Variables#

DEFAULT_REQUEST_COMMAND#

const DEFAULT_REQUEST_COMMAND: "spaces_mcp_request" = "spaces_mcp_request";

DEFAULT_SHUTDOWN_COMMAND#

const DEFAULT_SHUTDOWN_COMMAND: "spaces_mcp_shutdown" = "spaces_mcp_shutdown";

PROTOCOL_VERSION#

const PROTOCOL_VERSION: "2025-06-18" = "2025-06-18";

The MCP revision offered. The Rust server accepts 2025-06-18, 2025-03-26 and 2024-11-05, and answers with the one it picked.

SESSION_HEADER#

const SESSION_HEADER: "mcp-session-id" = "mcp-session-id";

Functions#

textOf()#

function textOf(content): string;

Concatenate the text parts, which is what almost every caller wants.

Parameters#

Parameter	Type
`content`	`ContentPart`[]

Returns#

string