> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beta.b3os.org/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

Connect any MCP client to B3OS through the local stdio server or the remote endpoint, which tools each one lists, and how agents reach marketplace actions.

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](/quickstart/mcp#configure-it-by-hand) 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](/routines).

## Credentials

Actions that need a credential get it from a [vault connection](/vault), 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.