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

# Quickstart

> Connect Claude Desktop, claude.ai web, or the MCP Inspector to Propal in under 5 minutes.

## 1. Endpoint

The MCP server is available at:

```
https://api.propal.io/v1/mcp
```

It uses the [Streamable HTTP transport](https://modelcontextprotocol.io/docs/concepts/transports#streamable-http) and authenticates via OAuth 2.1.

## 2. Connect a client

<Tabs>
  <Tab title="Claude Desktop">
    Open `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or
    `%APPDATA%\Claude\claude_desktop_config.json` (Windows) and add a `propal` entry to `mcpServers`:

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "mcpServers": {
        "propal": {
          "command": "npx",
          "args": ["-y", "mcp-remote", "https://api.propal.io/v1/mcp"]
        }
      }
    }
    ```

    Restart Claude Desktop. On first use, a browser window opens to authorize
    your Propal organization — accept and you're connected.
  </Tab>

  <Tab title="Claude.ai (web)">
    Open **Settings → Connectors** (or **Integrations**), click **Add custom MCP**, and enter:

    | Field | Value                          |
    | ----- | ------------------------------ |
    | Name  | `Propal`                       |
    | URL   | `https://api.propal.io/v1/mcp` |
    | Auth  | OAuth (auto-discovered)        |

    Claude redirects you to Propal to authorize, then you can use the
    `propal:*` tools in any chat.

    <Note>
      claude.ai web auto-stringifies object/array params before sending. The
      Propal MCP detects and handles this transparently — you don't need to
      do anything client-side.
    </Note>
  </Tab>

  <Tab title="ChatGPT">
    Open **Settings → Connectors → Add custom connector** in chatgpt.com or
    the desktop app, and enter:

    | Field          | Value                          |
    | -------------- | ------------------------------ |
    | Name           | `Propal`                       |
    | URL            | `https://api.propal.io/v1/mcp` |
    | Authentication | OAuth                          |

    OpenAI's connector framework handles OAuth 2.1 discovery automatically —
    accept the consent screen and the `propal_*` tools become available in
    any chat. Custom MCP connectors are available on Plus, Pro, Team, and
    Enterprise plans.

    <Note>
      Like claude.ai, ChatGPT may auto-stringify structured params. The
      Propal MCP handles this defensively — no client-side workaround
      needed.
    </Note>
  </Tab>

  <Tab title="Codex CLI">
    Add Propal to Codex's MCP config. Edit `~/.codex/config.toml` (or run
    `codex mcp add`):

    ```toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
    [mcp_servers.propal]
    command = "npx"
    args = ["-y", "mcp-remote", "https://api.propal.io/v1/mcp"]
    ```

    Then in any Codex session, the `propal_*` tools are available. The
    OAuth flow opens in your browser on first use.

    For headless / CI environments, set up a long-lived OAuth refresh by
    running an interactive `codex` session once on the same machine — the
    refresh token persists in `~/.mcp-auth/`.
  </Tab>

  <Tab title="Cursor">
    Open **Settings → Cursor Settings → MCP** (or edit
    `~/.cursor/mcp.json`) and add:

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "mcpServers": {
        "propal": {
          "url": "https://api.propal.io/v1/mcp"
        }
      }
    }
    ```

    Cursor supports remote MCP servers natively (no `mcp-remote` shim
    needed). Reload Cursor; the OAuth flow opens on first tool call.
  </Tab>

  <Tab title="Windsurf">
    Open **Windsurf → Settings → Cascade → MCP Servers**, click
    **Add Server**, choose **Remote (HTTP)**, and use:

    * **Name** — `Propal`
    * **URL** — `https://api.propal.io/v1/mcp`

    Windsurf handles OAuth via the built-in browser flow.
  </Tab>

  <Tab title="VS Code (Continue / Copilot)">
    For **Continue.dev**, edit `~/.continue/config.yaml`:

    ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}}
    mcpServers:
      - name: propal
        url: https://api.propal.io/v1/mcp
    ```

    For **GitHub Copilot Chat** with MCP support, follow the official
    [VS Code MCP guide](https://code.visualstudio.com/docs/copilot/chat/mcp-servers)
    and use the same URL.

    Most IDE plugins boil down to the same three values:

    * **URL** — `https://api.propal.io/v1/mcp`
    * **Transport** — Streamable HTTP
    * **Auth** — OAuth 2.1
  </Tab>

  <Tab title="MCP Inspector">
    Run the official inspector against the live server:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    npx @modelcontextprotocol/inspector https://api.propal.io/v1/mcp
    ```

    It opens a UI at `http://localhost:6274` where you can authenticate, list
    tools, and call them with structured input — perfect for exploration and
    debugging.
  </Tab>

  <Tab title="Custom client">
    If your client doesn't have a built-in MCP integration, point it at the
    same endpoint. The bare minimum:

    * **Endpoint** — `https://api.propal.io/v1/mcp`
    * **Transport** — Streamable HTTP (`POST` for requests, `GET` with
      `Accept: text/event-stream` for streaming)
    * **OAuth metadata** —
      `https://api.propal.io/v1/.well-known/oauth-authorization-server`
    * **Required scope** — `mcp:use` (granted by default on consent)

    The MCP SDK in any major language (`@modelcontextprotocol/sdk`,
    `mcp` Python package, `mcp-go`, etc.) handles transport + OAuth out of
    the box — just supply the URL.
  </Tab>
</Tabs>

## 3. First call — list components

Once connected, ask the agent to list the available DSL components:

```
List the available Propal components and their constraints.
```

The agent will call `list_propal_components` and surface the catalog (sections,
blocks, cards, tables, gallery, embed) plus the structural rules (no nested
sections, columns count must match, etc.).

## 4. Build your first section

Try:

```
Create a new proposal called "Q2 redesign" for lead Acme. Add an intro section
with a badge "Welcome", a title, a 3-paragraph description, and three goals
as numbered callouts.
```

The agent will chain:

<Steps>
  <Step title="create_proposal">
    Creates a blank proposal and returns its `id`.
  </Step>

  <Step title="list_propal_components / get_propal_component_schema">
    (Optional) Discovery if the agent isn't yet familiar with the grammar.
  </Step>

  <Step title="validate_propal_component_tree (optional)">
    Sanity-check the tree without writing.
  </Step>

  <Step title="append_propal_component_tree_to_proposal">
    Validates, assembles, and atomically appends the section(s) to the
    proposal document.
  </Step>
</Steps>

## 5. Inspect the result

Read what the agent produced:

```
Show me the structure of that proposal.
```

Calls `get_proposal_tree`, returns the document mapped to DSL — sections with
indices the agent can target for further edits.

## 6. Iterate

Anything from this point is a normal MCP tool call:

* `update_section_at_index` to rewrite a section
* `set_proposal_section_attrs` to swap the section style or background
* `find_and_replace_in_proposal` for bulk text edits
* `apply_theme_to_proposal` to change the design

See [editing](/mcp/editing) and [theming](/mcp/theming) for the full flow.

## What's next

<CardGroup cols={2}>
  <Card title="Authentication" icon="lock" href="/mcp/authentication">
    How OAuth 2.1, consent, and the `mcp:use` scope work.
  </Card>

  <Card title="Components DSL" icon="layout-grid" href="/mcp/components-dsl">
    The typed grammar for building proposal content.
  </Card>

  <Card title="Theming" icon="palette" href="/mcp/theming">
    Three ways to create themes, plus apply/detach/per-section.
  </Card>

  <Card title="Editing" icon="pencil" href="/mcp/editing">
    Read, mutate, and reorder existing proposals.
  </Card>
</CardGroup>