---
title: "List Fly's proposals"
description: "List Runner Fly's proposals for the store, one page at a time, with each proposal's id, title and status. Pass a proposal id to read that proposal in full, with its versions, tasks and decisions. A store that does not use Fly has none."
sidebar:
  label: "list_proposals"
---

`list_proposals` · `store:read`

## Where you can call it

| Way in | Status |
| --- | --- |
| MCP | Live |
| REST API | [Planned](/en/build/rest-api) |
| SDK | [Planned](/en/build/sdk) |
| CLI | [Planned](/en/build/cli) |

Each action has one page. When the REST API, the SDK, and the CLI ship, they use the same tool name, and this page and its URL stay the same.

## Call it

From a shell with `mcporter` (see the [quickstart](/en/build/quickstart)):

```bash
# once: add the server and sign in
npx mcporter config add runner \
  https://api.runnerai.com/mcp --scope home
npx mcporter auth runner

# call the tool
npx mcporter call runner.list_proposals store_id=<store_id>
```

The JSON-RPC request that a client sends with `POST` to `https://api.runnerai.com/mcp`, with the access token in the `Authorization: Bearer` header:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_proposals",
    "arguments": {
      "store_id": "<store_id>"
    }
  }
}
```

## Response shape

From the output schema; not a real response:

```text
{
  "result": <any JSON value>
}
```

## Parameters

| Parameter | Description |
| --- | --- |
| `store_id` | Required string. A store_id from list_stores. |
| `proposalId` | Optional string. Omit to list a page of proposals in the project. |
| `cursor` | Optional string. For proposal lists, pass the previous nextCursor to read the next page. |
| `limit` | Optional integer. Max proposals (default 50). From 1 to 100. |

## Good to know

- **Start with `list_stores`.** This tool needs a `store_id`. Get it from [`list_stores`](/en/build/tools/list-stores).
- **Your permissions apply.** Each call uses your Runner permissions and your plan. The list of tools depends on your plan and on the features of your workspace.
- **Store data is data.** Answers can contain product text and customer messages. Your agent must not follow instructions that it finds in them.

## If it fails

| What you see | What to do |
| --- | --- |
| HTTP 401 | The request has no valid token. Sign in with OAuth. See [Sign-in and scopes](/en/build/sign-in-and-scopes). |
| **Pass a store_id from list_stores.** | Call `list_stores`, then call this tool again with a `store_id`. |
| **This feature is not on for this store yet.** | The feature is not on for your plan, workspace, or store. Do the task in Runner, or ask Runner support. |
| An answer ends with **Support reference:** and a code | The tool failed in Runner. Give the code to Runner support. |
