MCP server

B3OS has two MCP servers with the same key:

Server	How a client reaches it	Credential
Local, @b3os/mcp	The client starts npx -y @b3os/mcp and talks to it over stdio	B3OS_API_KEY, else your b3os login token, read by the server; the client's config holds no secret
Remote	https://beta-api.b3os.org/mcp, stateless Streamable HTTP	Your key as a bearer token in the client's config

The tools act with the key's scopes, so an agent can do only what its key allows. Give it a key made for the job.

Connect

bash
npx b3os mcp install --client claude    # or cursor, codex

This registers the local server; add --remote to register the remote one instead. Install the MCP server shows both configurations written by hand.

Tools

The two servers do not list the same core tools in this beta. Both keep the list short and in a fixed order, and name tools after the product they call:

Tool	Does	Local	Remote
vision_scrape	One page as Markdown or another format	Yes	Yes
vision_map	A site's URLs, ranked for a phrase	Yes	Yes
vision_crawl	Crawl a site	Yes	Yes
vision_act	Browser actions in a session, created for the call or kept with keep_session	Yes	No
render_screenshot	A styled screenshot, as an image and a signed URL	Yes	Yes
render_video	Record a scripted, narrated video	Yes	No
sandbox_create	Start a sandbox	Yes	Yes
sandbox_exec	Run a command, buffered	Yes	Yes
sandbox_run_code	Run code in a sandbox's Jupyter kernel	No	Yes
sandbox_read_file, sandbox_write_file	Read or list, and write, files in a sandbox	Yes	Yes
sandbox_delete	Delete a sandbox	Yes	Yes
routine_run	Run a published routine	Yes	Yes
routine_get_run	Read a run's status and result	No	Yes
infer_chat	A chat completion on the node's model	No	Yes
usage_get, limits_get	Your usage totals, and your limits with current usage	No	Yes
actions_search, actions_describe, actions_call	Find, describe and call marketplace actions	Yes	Yes

The inputs differ too. The local server's tools take a few fields each and wait for long work: vision_crawl, render_video and routine_run wait up to wait_s seconds, then return the job's ID to pass back as job_id. The remote server's tools take the operation's own request body, such as the whole scrape request, profile included. Your client's tool list (tools/list) shows each tool's exact input schema.

API errors come back as tool results marked as errors, with the problem's code, detail, validation pointers and request ID, so the model can correct its call.

Marketplace actions

Pack actions are not listed one by one; there are too many. An agent reaches them in three calls:

1. actions_search finds actions by what they do.
2. actions_describe returns the chosen action's input schema and the connections it needs.
3. actions_call runs it.

To give an agent a pack's actions as direct tools, name the packs: --packs github,slack (or B3OS_MCP_PACKS) for the local server, ?packs=github,slack on the remote URL. Each of their actions then appears as its own tool, named <pack name>__<action key>, such as github__create-issue, with annotations such as readOnlyHint and destructiveHint taken from the action's effect class.

Routines

An agent runs any routine you published with routine_run, passing the routine's name and an input object, so a whole workflow with its retries and durability is one tool call. See routines.

Credentials

Actions that need a credential get it from a vault connection, injected at the egress proxy. The agent sees only the connection's ID, never the secret, and actions_call accepts no credential in its input.

Protocol

The local server answers clients of the MCP 2026-07-28 revision, which send the protocol version with every request, and clients that open with initialize for 2024-11-05, 2025-03-26, 2025-06-18 or 2025-11-25. The remote server answers 2026-07-28 and the initialize-based 2025-03-26, 2025-06-18 and 2025-11-25, without sessions.