Quickstart - Propal

1. Endpoint

The MCP server is available at:

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

It uses the Streamable HTTP transport and authenticates via OAuth 2.1.

2. Connect a client

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:

{
  "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.

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.

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.

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.

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

Add Propal to Codex’s MCP config. Edit ~/.codex/config.toml (or run codex mcp add):

[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/.

Open Settings → Cursor Settings → MCP (or edit ~/.cursor/mcp.json) and add:

{
  "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.

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.

For Continue.dev, edit ~/.continue/config.yaml:

mcpServers:
  - name: propal
    url: https://api.propal.io/v1/mcp

For GitHub Copilot Chat with MCP support, follow the official VS Code MCP guide 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

Run the official inspector against the live server:

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.

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.

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:

create_proposal

Creates a blank proposal and returns its id.

list_propal_components / get_propal_component_schema

(Optional) Discovery if the agent isn’t yet familiar with the grammar.

validate_propal_component_tree (optional)

Sanity-check the tree without writing.

append_propal_component_tree_to_proposal

Validates, assembles, and atomically appends the section(s) to the proposal document.

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 and theming for the full flow.

What’s next

Authentication

How OAuth 2.1, consent, and the mcp:use scope work.

Components DSL

The typed grammar for building proposal content.

Theming

Three ways to create themes, plus apply/detach/per-section.

Editing

Read, mutate, and reorder existing proposals.

Documentation Index

​1. Endpoint

​2. Connect a client

​3. First call — list components

​4. Build your first section

​5. Inspect the result

​6. Iterate

​What’s next

Authentication

Components DSL

Theming

Editing

1. Endpoint

2. Connect a client

3. First call — list components

4. Build your first section

5. Inspect the result

6. Iterate

What’s next