## Setup [#setup]

<Steps>
  <Step>
    ### Claude Code [#claude-code]

    Run the following command in your terminal:

    ```bash
    claude mcp add --transport http --scope user cubitt https://cubitt.tilt.legal/mcp
    ```

    Then run `/mcp` in your Claude Code session to connect.
  </Step>

  <Step>
    ### Cursor [#cursor]

    Add the following to your `.cursor/mcp.json` file:

    ```json
    {
      "mcpServers": {
        "cubitt": {
          "url": "https://cubitt.tilt.legal/mcp"
        }
      }
    }
    ```
  </Step>

  <Step>
    ### Codex CLI/IDE [#codex-cliide]

    Add the following to your `.codex/config.toml` file:

    ```toml
    [mcp_servers.cubitt]
    url = "https://cubitt.tilt.legal/mcp"
    ```
  </Step>

  <Step>
    ### OpenCode [#opencode]

    Run the interactive CLI command to add the server:

    ```bash
    opencode mcp add
    ```

    Select **remote**, name it `cubitt`, and paste the URL `https://cubitt.tilt.legal/mcp`.

    Or add it manually to your `opencode.json` config file:

    ```json
    {
      "mcp": {
        "cubitt": {
          "type": "remote",
          "url": "https://cubitt.tilt.legal/mcp"
        }
      }
    }
    ```
  </Step>

  <Step>
    ### Claude Desktop [#claude-desktop]

    Claude Desktop doesn't support remote MCP servers via JSON config.
    Instead, go to **Settings → Connectors → Add custom connector** in the UI
    and paste the URL:

    ```
    https://cubitt.tilt.legal/mcp
    ```
  </Step>
</Steps>

***

## Canary Docs [#canary-docs]

To use docs from the `development` branch instead of production, replace the URL with the canary deployment. The canary deployment is protected by Vercel, so you'll need to pass a bypass header using the `VERCEL_BYPASS` environment variable.

```bash
claude mcp add -s user -t http cubitt-canary https://cubitt-env-canary-tilt-legal.vercel.app/mcp -H "x-vercel-protection-bypass: $VERCEL_BYPASS"
```

For other tools, use the canary URL `https://cubitt-env-canary-tilt-legal.vercel.app/mcp` and include the `x-vercel-protection-bypass` header with your bypass token.

***

## Available Tools [#available-tools]

### `search_docs` [#search_docs]

Search or list Cubitt documentation pages with fuzzy search across titles, descriptions, and paths.

| Parameter | Type   | Required | Description                                                                                                           |
| --------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------- |
| `query`   | string | No       | Search term to find docs pages. Leave empty to list all docs                                                          |
| `section` | string | No       | Filter by section such as `get-started`, `primitives`, `composites`, `hooks`, `utilities`, `foundations`, or `guides` |
| `limit`   | number | No       | Maximum number of results (default: 20)                                                                               |
| `page`    | number | No       | Page number for pagination (default: 1)                                                                               |

### `get_doc_content` [#get_doc_content]

Fetch the full markdown content and metadata for a specific documentation page.

| Parameter | Type   | Required | Description                                                                             |
| --------- | ------ | -------- | --------------------------------------------------------------------------------------- |
| `path`    | string | Yes      | Documentation page path or slug (e.g., `primitives/button`, `get-started/installation`) |

### `search_icons` [#search_icons]

Search for Cubitt icons by name or tags. Returns matching icons with `componentName`, `importPath`, `category`, and `tags`.

| Parameter  | Type   | Required | Description                                                          |
| ---------- | ------ | -------- | -------------------------------------------------------------------- |
| `query`    | string | Yes      | Search query for icon names or tags (e.g., `star`, `arrow`, `user`)  |
| `category` | string | No       | Filter by icon category or `all` for all categories (default: `all`) |
| `limit`    | number | No       | Maximum number of results (default: 20, max: 50)                     |

***

## HTTP Endpoints [#http-endpoints]

These routes are exposed by the docs app (in addition to the UI routes).

### MCP (JSON-RPC over HTTP) [#mcp-json-rpc-over-http]

* `GET /mcp` — Returns `405 Method Not Allowed` in the current deployment; Cubitt intentionally exposes a POST-only MCP surface
* `POST /mcp` — MCP JSON-RPC requests

### MCP Catalogs (Sitemap, Icons) [#mcp-catalogs-sitemap-icons]

* `GET /mcp/docs` — Docs catalog (JSON sitemap/tree; includes `mdUrl` links)
* `GET /mcp/icons` — Icon catalog used by `search_icons`

### Public API (Non-MCP) [#public-api-non-mcp]

* `GET /api/health` — App health/status endpoint for monitoring and uptime checks
* `GET /api/search` — Docs search endpoint used by the site UI
* `GET /api/icon-gallery` — Icon SVG data (used by Raycast extension)
* `POST /api/deepwiki/chat` — DeepWiki chat proxy

### LLM / Markdown Export [#llm--markdown-export]

* `GET /<path>.md` — Raw markdown for single page
* `GET /<path>` with `Accept: text/markdown` — Raw markdown for a single page via content negotiation (no redirect)
* `GET /llms.txt` — LLM-friendly index of key pages
* `GET /llms-full.txt` — Full docs dump as plain text

#### Markdown access patterns (browser vs agent) [#markdown-access-patterns-browser-vs-agent]

* **Browsers / humans:** request the normal page URL (e.g. `/get-started/mcp`) to get the HTML page.
* **Agents:** request the normal URL and, via content negotiation, send `Accept: text/markdown` to receive markdown at the same URL (no redirect).

### SEO [#seo]

* `GET /robots.txt` — Robots directives. Auto generated, always in sync.
* `GET /sitemap.xml` — Sitemap for public pages. Auto generated, always in sync.

### Open Graph Images [#open-graph-images]

* `GET /og/<path>` — Generated Open Graph image for a doc page (e.g. `/og/get-started/mcp`)