> ## 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.

# MCP introduction

> Build, edit, and theme proposals from any MCP-compatible AI agent.

The Propal **MCP server** exposes the same data and operations as our REST API,
but tailored for AI agents through the [Model Context Protocol](https://modelcontextprotocol.io). Plug it into your favorite
AI assistant — Claude Desktop, Claude.ai, ChatGPT, Codex, Cursor, Windsurf,
VS Code, the MCP Inspector, or any custom client — and let an agent draft,
edit, restructure, and theme proposals on your behalf, with end-to-end type
safety on every call.

## Supported clients

Any MCP-compatible client connects with the same endpoint + OAuth flow.
Setup details for each client are in the [quickstart](/mcp/quickstart):

<CardGroup cols={3}>
  <Card title="Claude Desktop" icon="message-circle" href="/mcp/quickstart">
    Anthropic's desktop app via `mcp-remote`.
  </Card>

  <Card title="Claude.ai" icon="globe" href="/mcp/quickstart">
    Custom connector in Settings → Integrations.
  </Card>

  <Card title="ChatGPT" icon="sparkles" href="/mcp/quickstart">
    Custom connector (Plus, Pro, Team, Enterprise).
  </Card>

  <Card title="Codex CLI" icon="terminal" href="/mcp/quickstart">
    OpenAI's coding agent — `~/.codex/config.toml`.
  </Card>

  <Card title="Cursor" icon="cursor" href="/mcp/quickstart">
    Native remote MCP via Settings → MCP.
  </Card>

  <Card title="Windsurf" icon="wind" href="/mcp/quickstart">
    Cascade → MCP Servers → Remote (HTTP).
  </Card>

  <Card title="VS Code" icon="code" href="/mcp/quickstart">
    Continue.dev, Copilot Chat, or any MCP-aware extension.
  </Card>

  <Card title="MCP Inspector" icon="search" href="/mcp/quickstart">
    Browser UI for exploration and debugging.
  </Card>

  <Card title="Custom client" icon="plug" href="/mcp/quickstart">
    Any MCP SDK in any language.
  </Card>
</CardGroup>

## Why MCP instead of REST?

|                          | REST API                             | MCP server                                                            |
| ------------------------ | ------------------------------------ | --------------------------------------------------------------------- |
| Audience                 | Developers, integrations, dashboards | AI agents (Claude, ChatGPT, Codex, Cursor, Windsurf, VS Code, custom) |
| Discovery                | OpenAPI spec                         | Live tool catalog (`list_propal_components`, schemas on demand)       |
| Auth                     | API key (Bearer)                     | OAuth 2.1 (`mcp:use` scope)                                           |
| Composition              | Manual orchestration                 | The agent picks tools and chains calls                                |
| Editing proposal content | Not exposed                          | Full Propal DSL (read + write)                                        |
| Theming                  | CRUD only                            | Presets, smart palette, advanced, apply/detach                        |

If your goal is human-built integrations, use the [REST API](/api-reference/introduction). If you want an agent
to *think* about your proposal — generate a section, restyle a paragraph,
swap a theme — the MCP is the right surface.

## What you can do

<CardGroup cols={2}>
  <Card title="Compose proposals" icon="layout-dashboard" href="/mcp/components-dsl">
    Build sections from a typed DSL: paragraphs, headings, columns, cards,
    pricing tables, galleries, embeds. The agent assembles the document
    block-by-block, not a TipTap blob.
  </Card>

  <Card title="Edit existing proposals" icon="pencil" href="/mcp/editing">
    Read the current tree as DSL, insert/update/delete sections by index,
    reorder, or run a project-wide find & replace.
  </Card>

  <Card title="Control theming" icon="palette" href="/mcp/theming">
    Pick a preset, generate a theme from a mini-palette, or go advanced with
    full token control. Apply, detach, and patch per-section.
  </Card>

  <Card title="Manage everything else" icon="database" href="/mcp/tools">
    Leads, proposals metadata, media, catalog, templates, organization,
    metrics — all available as MCP tools.
  </Card>
</CardGroup>

## Endpoint

The MCP server lives at:

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

It uses the **Streamable HTTP** transport. OAuth 2.1 metadata is published at
`/v1/.well-known/oauth-authorization-server` so MCP clients can discover the
authorization server automatically.

## Tool count

The server currently exposes **68 tools** across 9 domains:

* `organization` (2) — read org details and members
* `metrics` (7) — pipeline, conversion, sales, etc.
* `themes` (5) + `theming` (9) — CRUD plus presets, palette, palette validation, apply/detach, resolved style, per-section attrs
* `catalog` (8) — items and bundles
* `templates` (4) — list/create-from-proposal/delete
* `leads` (6) — CRUD + linked proposals
* `media` (7) — files, folders, signed upload URLs
* `proposals` (10) — CRUD + publish/unpublish/duplicate
* `components` (4) + `editing` (6) — Propal DSL discovery, validation, append, plus read/insert/update/delete/reorder/find & replace

Use [`list_propal_components`](/mcp/components-dsl) for live discovery; the
catalog evolves with the product.

## What's next

<Steps>
  <Step title="Get connected">
    Follow the [quickstart](/mcp/quickstart) to attach Claude Desktop or the
    MCP Inspector in under 5 minutes.
  </Step>

  <Step title="Understand authentication">
    [OAuth 2.1](/mcp/authentication) handles consent, token refresh, and
    scope enforcement — see how it works and what `mcp:use` unlocks.
  </Step>

  <Step title="Learn the component DSL">
    The [components DSL](/mcp/components-dsl) is the heart of the MCP — a
    typed grammar that produces valid editor content without exposing raw
    TipTap JSON.
  </Step>
</Steps>

## Not in v1

* Webhooks
* Multi-tool transactions (each mutation is independent; agents serialize
  themselves and refetch between calls — see [editing](/mcp/editing))
* External URLs on `image` / `icon` / `video` (placeholders only — `embed`
  accepts URLs, see [components DSL](/mcp/components-dsl#media))
* Section nesting (a `section` cannot contain another `section`)