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

# gavai mcp

> Serve the Builder MCP server over stdio so any MCP host can drive the active workspace.

export const ErrorTable = ({errors}) => <div className="gv-error-table" role="table" aria-label="Errors and fixes">
    <div className="gv-error-table__head" role="row">
      <span className="gv-error-table__col-head" role="columnheader">Error</span>
      <span className="gv-error-table__col-head" role="columnheader">Cause</span>
      <span className="gv-error-table__col-head" role="columnheader">Fix</span>
    </div>
    {errors.map((err, i) => <div className="gv-error-table__row" role="row" key={i}>
        <code className="gv-error-table__code" role="cell">{err.code}</code>
        <div className="gv-error-table__cause" role="cell">{err.cause}</div>
        <div className="gv-error-table__fix" role="cell">{err.fix}</div>
      </div>)}
  </div>;

export const Def = ({term, type, defaultValue, required, children}) => <>
    <dt className="gv-def-list__term">
      <span className="gv-def-list__name">{term}</span>
      {type && <span className="gv-def-list__type">{type}</span>}
      {required && <span className="gv-def-list__required">required</span>}
      {defaultValue !== undefined && <span className="gv-def-list__default">
          default <code>{defaultValue}</code>
        </span>}
    </dt>
    <dd className="gv-def-list__description">{children}</dd>
  </>;

export const DefList = ({children}) => <dl className="gv-def-list">{children}</dl>;

export const BrandCard = ({eyebrow, title, href, icon, badge, cta, featured = false, horizontal = false, children}) => {
  const classes = ["gv-card", featured && "gv-card--featured", horizontal && "gv-card--horizontal"].filter(Boolean).join(" ");
  const inner = <>
      {icon && <span className="gv-card__icon" aria-hidden="true">
          <Icon icon={icon} />
        </span>}
      <div className="gv-card__main">
        {(eyebrow || badge) && <div className="gv-card__meta">
            {eyebrow && <Eyebrow label={eyebrow} tone="muted" />}
            {badge && <span className="gv-card__badge">{badge}</span>}
          </div>}
        <h3 className="gv-card__title">{title}</h3>
        {children && <div className="gv-card__body">{children}</div>}
        {cta && <span className="gv-card__cta">
            {cta}
            <svg className="gv-card__cta-arrow" viewBox="0 0 24 24" width="12" height="12" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
              <line x1="7" y1="17" x2="17" y2="7" />
              <polyline points="7 7 17 7 17 17" />
            </svg>
          </span>}
      </div>
    </>;
  return href ? <a className={classes} href={href}>
      {inner}
    </a> : <div className={classes}>{inner}</div>;
};

export const ArrowItem = ({children}) => <li className="gv-arrow-item">
    <span className="gv-arrow-item__arrow" aria-hidden="true">{"↳︎"}</span>
    <span className="gv-arrow-item__content">{children}</span>
  </li>;

export const ArrowList = ({children}) => <ul className="gv-arrow-list">{children}</ul>;

export const Eyebrow = ({label, tone = "default"}) => <div className={`gv-eyebrow gv-eyebrow--${tone}`}>
    <span className="gv-eyebrow__bar" aria-hidden="true" />
    <span className="gv-eyebrow__label">{label}</span>
  </div>;

<Eyebrow label="CLI" />

Start the Builder MCP server and speak the JSON-RPC stdio transport defined by the Model Context Protocol. This page covers the synopsis, how to register the server with Claude Desktop, the tools the server exposes, and the security boundary you take on by enabling it.

## Synopsis

```bash theme={null}
gavai mcp
```

## Subcommands

<DefList>
  <Def term="install <host>" type="subcommand">
    Write the correct MCP server entry into the named host's config file. Supported hosts: `claude-desktop`.
  </Def>
</DefList>

## Flags

<Note>
  Run `gavai mcp --help` for the authoritative flag list. The CLI is the source of truth.
</Note>

## Behavior

`gavai mcp` is designed to be spawned by an MCP host — Claude Desktop, Cursor, Windsurf, or any other client that supports stdio-based MCP servers — not run interactively. The process reads JSON-RPC requests on stdin and writes responses to stdout.

The server reuses the credentials stored at `~/.config/gavai/credentials.json`. Run `gavai login` at least once on the machine before registering the server with any host.

## Register with an MCP host

<Tabs>
  <Tab title="Via CLI">
    The fastest path is the `install` subcommand:

    ```bash theme={null}
    gavai mcp install claude-desktop
    ```

    The CLI writes the correct entry into Claude Desktop's config file. Restart Claude Desktop after running it.
  </Tab>

  <Tab title="Manual config">
    Open the Claude Desktop config for your OS:

    <ArrowList>
      <ArrowItem>**macOS** — `~/Library/Application Support/Claude/claude_desktop_config.json`</ArrowItem>
      <ArrowItem>**Windows** — `%APPDATA%\Claude\claude_desktop_config.json`</ArrowItem>
    </ArrowList>

    Add the `gavai-builder` entry under `mcpServers`:

    ```json claude_desktop_config.json theme={null}
    {
      "mcpServers": {
        "gavai-builder": {
          "command": "gavai",
          "args": ["mcp"]
        }
      }
    }
    ```

    Save the file and restart Claude Desktop.
  </Tab>
</Tabs>

## Tools exposed

The server registers fourteen tools with the host: `list_tenants`, `get_tenant`, `get_tenant_app`, `patch_tenant_app`, `publish_tenant_version`, `list_block_types`, `get_block_schema`, `list_components`, `get_component_schema`, `get_component_examples`, `get_tenant_theme`, `publish_tenant_theme`, and `patch_tenant_theme`. Each tool's input schema is discoverable through the standard MCP `tools/list` call. See [Builder MCP reference](/mcp/builder-mcp) for the per-tool documentation.

## Security

The MCP server runs with the same permissions as your CLI session token. Any tool call the host makes — patch, publish, theme update — executes against the active workspace with your credentials.

<Warning>
  Treat the connected workspace as if it were production. Use a dedicated test workspace for experimentation, and run `gavai logout` to invalidate the local session when you no longer need MCP access.
</Warning>

## Exit codes

<ErrorTable
  errors={[
{ code: "0", cause: "Server exited cleanly. Host closed stdin.", fix: "—" },
{ code: "2", cause: "Invalid arguments (e.g., unknown subcommand).", fix: "Run `gavai mcp --help` for the supported subcommands." },
{ code: "3", cause: "Not authenticated.", fix: "Run `gavai login` first, then re-register the server with the host." },
{ code: "7", cause: "Network error connecting to the API on startup.", fix: "Check the network. Retry once the connection is back." },
]}
/>

See [CLI overview — exit codes](/cli/overview#exit-codes) for the full table.

<BrandCard eyebrow="REFERENCE" title="Builder MCP" href="/mcp/builder-mcp">
  Full tool list, input schemas, and auth details for the Builder MCP server.
</BrandCard>