# Cap Table

Access cap table data, grants, convertible instruments, waterfall models, 409A valuations, financing history, and governance data for companies you have access to in Carta.

For setup and authentication, see the [Setup guide](./setup.md).

***

## Overview

Cap table tools use four MCP tools: `get_current_user`, `list_accounts`, `discover`, and `fetch`. The primary entry points are `fetch` (to run a command) and `discover` (to browse what's available). All tools are read-only.

Tools appear in your MCP client as `mcp__Carta__<tool_name>`.

***

## Tools

### `get_current_user`

Get the authenticated Carta user's profile — id, email, and full name.

*No parameters.*

**Example:**

> "Who am I logged in as?"

***

### `list_accounts`

List all companies and organizations the current user has access to — the same accounts shown in the Carta account switcher.

*No parameters.*

Returns `name`, `id` (format: `corporation_pk:<id>`), `type`, and `status`. Use the numeric portion of `id` as `corporation_id` in `fetch` commands.

**Example:**

> "What companies do I have access to?"

***

### `discover`

Browse available cap table commands before calling `fetch`. Returns command names, descriptions, required and optional parameters.

| Parameter | Required | Description                                   |
| --------- | -------- | --------------------------------------------- |
| `scope`   | No       | Filter by `"read"`, `"compute"`, or `"write"` |
| `search`  | No       | Keyword filter on command name or description |

**Example:**

> "What cap table data can I access?"

***

### `fetch`

Execute a named cap table command. Use `discover` first to find the command name and required parameters.

| Parameter | Required | Description                                           |
| --------- | -------- | ----------------------------------------------------- |
| `command` | Yes      | Command name (e.g. `"cap_table:get:409a_valuations"`) |
| `params`  | Yes      | Parameters dict (e.g. `{"corporation_id": 12345}`)    |

Pass `"raw": true` in `params` to skip response formatting and return the full API response.

***

## Available Commands

### Cap Table

| Command                                  | Required Params  | Description                                                                                                                   |
| ---------------------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `cap_table:get:cap_table_by_share_class` | `corporation_id` | Cap table grouped by share class — authorized, outstanding, and fully diluted shares with ownership %                         |
| `cap_table:get:cap_table_by_stakeholder` | `corporation_id` | Cap table grouped by stakeholder/shareholder with holdings and ownership %                                                    |
| `cap_table:get:stakeholders`             | `corporation_id` | List stakeholders with name, email, and role. Optional: `search`. For ownership data, use `cap_table_by_stakeholder` instead. |

**Examples:**

> "Show me the cap table for \[Company] by share class"
>
> "Who are the stakeholders at \[Company]?"

***

### Grants

| Command                       | Required Params              | Description                                                                                                        |
| ----------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `cap_table:list:grants`       | `corporation_id`             | Option grants summary (all grants), or filtered by holder name/grant number with `search`                          |
| `cap_table:get:grant_vesting` | `corporation_id`, `grant_id` | Vesting schedule for a specific grant — total, vested, and unvested shares, cliff summary, and full event timeline |

**Examples:**

> "Summarize the option grants at \[Company]"
>
> "Show me the vesting schedule for grant #1234"

***

### Waterfall & Pro-Forma

| Command                             | Required Params  | Description                                                                       |
| ----------------------------------- | ---------------- | --------------------------------------------------------------------------------- |
| `cap_table:get:waterfall_scenarios` | `corporation_id` | Saved exit waterfall models with per-holder payout breakdown and return multiples |
| `cap_table:get:pro_forma_models`    | `corporation_id` | Saved pro-forma round models with inputs, outputs, and investor breakdown         |

**Examples:**

> "What do the waterfall scenarios look like for \[Company]?"
>
> "Show me the pro-forma models for \[Company]"

***

### Convertible Instruments

| Command                            | Required Params  | Description                                                                                                               |
| ---------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `cap_table:get:convertible_notes`  | `corporation_id` | All SAFEs and convertible notes combined — `is_debt` field distinguishes them                                             |
| `cap_table:list:convertible_notes` | `corporation_id` | Convertible instruments with pagination and status filtering. Optional: `page`, `pageSize`, `search`, `statusExplanation` |
| `cap_table:list:safes`             | `corporation_id` | SAFEs only (dedicated endpoint)                                                                                           |

**Examples:**

> "What SAFEs and convertible notes does \[Company] have outstanding?"
>
> "Show me all outstanding SAFEs for \[Company]"

***

### Valuations & Financing

| Command                           | Required Params  | Description                                                                                                        |
| --------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------ |
| `cap_table:get:409a_valuations`   | `corporation_id` | 409A FMV history — effective dates, expiration dates, and price per share. Optional: `share_class_id`, `report_id` |
| `cap_table:get:financing_history` | `corporation_id` | Financing history aggregated by round — cash raised, investor count, share count, and close dates                  |

**Examples:**

> "What are the 409A valuations for \[Company]?"
>
> "Show me the full financing history for \[Company]"

***

### Governance

| Command                                | Required Params  | Description                                                                              |
| -------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------- |
| `cap_table:get:rights_and_preferences` | `corporation_id` | Share class rights and preferences — voting power, liquidation seniority, and stock type |

**Example:**

> "What are the rights and preferences for \[Company]'s share classes?"

***

## OAuth Scope

Cap table tools require the `readwrite_mcp_companies` scope. This is requested automatically on first authentication — no manual configuration needed.

Access is governed by your existing Carta account permissions. If your account doesn't have access to a company, requests for that company's data will be rejected.