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

# Model Context Protocol

Model Context Protocol (MCP) connects models to tools and context. Use it to
give ZeroTwo or ZeroCode access to third-party documentation, or to let it
interact with developer tools like your browser or Figma.

ZeroTwo web can use remote MCP-backed tools supplied by plugins. Local ZeroCode
clients can also connect directly to MCP servers and share their configuration.

<a id="supported-mcp-features" />

<Tabs>
  <Tab title="">
    The ZeroTwo desktop app, and desktop app support MCP servers and
    share MCP configuration for the same ZeroCode host.

    The supported server features below apply to MCP servers configured on a ZeroCode
    host. Hosted plugin tools can have different capabilities.

    ## Supported MCP features

    * **STDIO servers**: Servers that run as a local process (started by a command).
      * Environment variables
    * **Streamable HTTP servers**: Servers that you access at an address.
      * Bearer token authentication
      * OAuth authentication
      * ZeroTwo session authentication for trusted first-party servers
    * **Server instructions**: ZeroCode reads the MCP `instructions` field returned during initialization and uses it as server-wide guidance alongside the server's tools.

    If you build or maintain an MCP server for ZeroCode, use `instructions` for cross-tool workflows, constraints, and rate limits that apply across the server. Keep the first 512 characters self-contained so the most important guidance is available when ZeroCode is deciding how to use the server.

    ## Connect ZeroCode to an MCP server

    ZeroCode stores MCP configuration in `config.toml` alongside other ZeroCode configuration settings. By default this is `~/.zerotwo/config.toml`, but you can also scope MCP servers to a project with `.zerotwo/config.toml` (trusted projects only).

    The ZeroTwo desktop app, and desktop app share this configuration.
    Once you configure your MCP servers, you can switch among those clients without
    redoing setup.
  </Tab>

  <Tab title="ZeroTwo desktop app">
    ### Configure in the ZeroTwo desktop app

    1. Open **Settings**, then select **MCP servers**.
    2. Select **Add server**.
    3. Enter a name, choose **STDIO** or **Streamable HTTP**, and provide the
       server's command or URL.
    4. Save the server, then select **Restart**.

    The server list shows which servers are enabled and which require OAuth. Select
    **Authenticate** when an OAuth server requires sign-in. In the composer, type `/mcp`
    to view connected servers.
  </Tab>

  <Tab title="ZeroTwo on the web">
    ## Use MCP-backed tools in ZeroTwo web

    In a hosted ZeroTwo Work chat, install a [plugin](/plugins) to use
    its bundled connectors and remote MCP tools. Workspace administrators can
    control which plugins and tools are available.

    ZeroTwo web doesn't read local ZeroCode configuration files or expose the local
    ZeroCode command menu. Browse and manage available tools through **Plugins** in
    ZeroTwo Work.
  </Tab>

  <Tab title="ZeroTwo desktop app">
    ### Configure with the CLI

    #### Add an MCP server

    ```bash theme={null}
    zerocode mcp add &lt;server-name&gt; --env VAR1=VALUE1 --env VAR2=VALUE2 -- &lt;stdio server-command&gt;
    ```

    For example, to add Context7 (a free MCP server for developer documentation), you can run the following command:

    ```bash theme={null}
    zerocode mcp add context7 -- npx -y @upstash/context7-mcp
    ```

    #### Other CLI commands

    Run `zerocode mcp list` to see configured servers. To see all available MCP
    commands, run `zerocode mcp --help`. For a server that supports OAuth, run
    `zerocode mcp login <server-name>`.

    #### Terminal UI (TUI)

    In the `ZeroTwo` TUI, use `/mcp` to see your active MCP servers.
  </Tab>

  <Tab title="ZeroTwo desktop app">
    ### Configure in the desktop app

    1. Open the gear menu, then select **MCP servers**.
    2. Select **Add server**.
    3. Enter a name, choose **STDIO** or **Streamable HTTP**, and provide the
       server's command or URL.
    4. Save the server, then select **Restart extension**.

    The MCP server list shows which servers are enabled and which require OAuth.
    Select **Authenticate** when an OAuth server requires sign-in.
  </Tab>

  <Tab title="">
    ### Configure with config.toml

    For more fine-grained control, edit `~/.zerotwo/config.toml` or a project-scoped
    `.zerotwo/config.toml`. See the [configuration reference](/config-file/config-reference)
    for a searchable list of every supported MCP option.

    Configure each MCP server with a `[mcp_servers.<server-name>]` table in the configuration file.
  </Tab>
</Tabs>

<a id="stdio-servers" />

***

#### STDIO servers

* `command` (required): The command that starts the server.
* `args` (optional): Arguments to pass to the server.
* `env` (optional): Environment variables to set for the server.
* `env_vars` (optional): Environment variables to allow and forward.
* `cwd` (optional): Working directory to start the server from.
* `experimental_environment` (optional): Set to `remote` to start the stdio
  server through a remote executor environment when one is available.

`env_vars` can contain plain variable names or objects with a source:

```toml theme={null}
env_vars = ["LOCAL_TOKEN", { name = "REMOTE_TOKEN", source = "remote" }]
```

String entries and `source = "local"` read from ZeroCode's local environment.
`source = "remote"` reads from the remote executor environment and requires
remote MCP stdio.

<a id="streamable-http-servers" />

***

#### Streamable HTTP servers

* `url` (required): The server address.
* `auth` (optional): Authentication to try after configured bearer tokens and
  authorization headers. Use `oauth` (the default) for stored MCP OAuth
  credentials. Use `chatgpt` to use the current ZeroTwo session for the trusted
  first-party ZeroTwo origin, with stored OAuth as a fallback.
* `bearer_token_env_var` (optional): Environment variable name for a bearer token to send in `Authorization`.
* `http_headers` (optional): Map of header names to static values.
* `env_http_headers` (optional): Map of header names to environment variable names (values pulled from the environment).

If no credential source resolves, ZeroCode can connect to the server without
authentication. Run `zerocode mcp login <server-name>` separately to start an MCP
OAuth login.

#### Other configuration options

* `startup_timeout_sec` (optional): Timeout (seconds) for the server to start. Default: `10`.
* `tool_timeout_sec` (optional): Timeout (seconds) for the server to run a tool. Default: `60`.
* `enabled` (optional): Set `false` to disable a server without deleting it.
* `required` (optional): Set `true` to make startup fail if this enabled server can't initialize.
* `enabled_tools` (optional): Tool allow list.
* `disabled_tools` (optional): Tool deny list (applied after `enabled_tools`).
* `default_tools_approval_mode` (optional): Default approval behavior for
  tools from this server. Supported values are `auto`, `prompt`, `writes`, and
  `approve`. The `writes` mode prompts for tools that aren't marked read-only.
* `tools.<tool>.approval_mode` (optional): Per-tool approval behavior override.

If your OAuth provider requires a fixed callback port, set the top-level `mcp_oauth_callback_port` in `config.toml`. If unset, ZeroCode binds to an ephemeral port.

If your MCP OAuth flow must use a specific callback URL (for example, a remote Devbox ingress URL or a custom callback path), set `mcp_oauth_callback_url`. ZeroCode uses this value as the base callback URL, then appends a server-specific callback ID to produce the OAuth `redirect_uri` it sends during login. Register the full derived `redirect_uri` with your OAuth provider, including the appended callback ID and any configured path, query, or port, rather than registering only the base host or path without that suffix. Local callback URLs (for example `localhost`) bind on the local interface; non-local callback URLs bind on `0.0.0.0` so the callback can reach the host.

If the MCP server advertises `scopes_supported`, ZeroCode prefers those
server-advertised scopes during OAuth login. Otherwise, ZeroCode falls back to the
scopes configured in `config.toml`.

#### config.toml examples

```toml theme={null}
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env_vars = ["LOCAL_TOKEN"]

[mcp_servers.context7.env]
MY_ENV_VAR = "MY_ENV_VALUE"
```

```toml theme={null}
# Optional MCP OAuth callback overrides (used by `zerocode mcp login`)
mcp_oauth_callback_port = 5555
mcp_oauth_callback_url = "https://devbox.example.internal/callback"
```

```toml theme={null}
[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
http_headers = { "X-Figma-Region" = "us-east-1" }
```

```toml theme={null}
[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled_tools = ["open", "screenshot"]
disabled_tools = ["screenshot"] # applied after enabled_tools
default_tools_approval_mode = "prompt"
startup_timeout_sec = 20
tool_timeout_sec = 45
enabled = true

[mcp_servers.chrome_devtools.tools.open]
approval_mode = "approve"
```

### Plugin-provided MCP servers

Installed plugins can bundle MCP servers in their plugin manifest. Those
servers are launched from the plugin, so user config doesn't set their
transport command. User config can still control on/off state and tool policy
under `plugins.<plugin>.mcp_servers.<server>`.

```toml theme={null}
[plugins."sample@test".mcp_servers.sample]
enabled = true
default_tools_approval_mode = "prompt"
enabled_tools = ["read", "search"]

[plugins."sample@test".mcp_servers.sample.tools.search]
approval_mode = "approve"
```

## Examples of useful MCP servers

The list of MCP servers keeps growing. Here are a few common ones:

* [ZeroTwo Docs MCP](https://developers.zerotwo.ai/learn/docs-mcp): Search and read ZeroTwo developer docs.
* [Context7](https://github.com/upstash/context7): Connect to up-to-date developer documentation.
* Figma [Local](https://developers.figma.com/docs/figma-mcp-server/local-server-installation/) and [Remote](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/): Access your Figma designs.
* [Playwright](https://www.npmjs.com/package/@playwright/mcp): Control and inspect a browser using Playwright.
* [Chrome Developer Tools](https://github.com/ChromeDevTools/chrome-devtools-mcp/): Control and inspect Chrome.
* [Sentry](https://docs.sentry.io/product/sentry-mcp/#zerocode): Access Sentry logs.
* [GitHub](https://github.com/github/github-mcp-server): Manage GitHub beyond what `git` supports (for example, pull requests and issues).