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

# MCP Setup

> Wire pull/story into any MCP-compatible agent in under 2 minutes.

## What is MCP?

[Model Context Protocol](https://modelcontextprotocol.io) (MCP) is Anthropic's open standard for giving AI agents access to tools. Any MCP-compatible client — Claude Code, Claude Desktop, Cursor, Windsurf — can call the pull/story tools once you wire up the MCP server.

## Install

<Steps>
  <Step title="Get an API key">
    [pullstory.com/dashboard/api-keys](https://pullstory.com/dashboard/api-keys) → **Create key**.
  </Step>

  <Step title="Pick your client">
    <Tabs>
      <Tab title="Claude Code">
        Edit `.mcp.json` in your project root:

        ```json theme={null}
        {
          "mcpServers": {
            "pullstory": {
              "command": "npx",
              "args": ["-y", "@pullstory/mcp@latest"],
              "env": { "PULLSTORY_API_KEY": "${PULLSTORY_API_KEY}" }
            }
          }
        }
        ```

        On native Windows, use `"command": "cmd"` and `"args": ["/c", "npx", "-y", "@pullstory/mcp@latest"]`.
      </Tab>

      <Tab title="Claude Desktop">
        Edit `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS or `%APPDATA%\Claude\claude_desktop_config.json` on Windows:

        ```json theme={null}
        {
          "mcpServers": {
            "pullstory": {
              "command": "npx",
              "args": ["-y", "@pullstory/mcp@latest"],
              "env": { "PULLSTORY_API_KEY": "${PULLSTORY_API_KEY}" }
            }
          }
        }
        ```

        On native Windows, use `"command": "cmd"` and `"args": ["/c", "npx", "-y", "@pullstory/mcp@latest"]`.
      </Tab>

      <Tab title="Cursor">
        `Cmd/Ctrl + Shift + J` → **MCP** → **Add new MCP server**:

        ```json theme={null}
        {
          "pullstory": {
            "command": "npx",
            "args": ["-y", "@pullstory/mcp@latest"],
            "env": { "PULLSTORY_API_KEY": "${PULLSTORY_API_KEY}" }
          }
        }
        ```
      </Tab>

      <Tab title="Windsurf">
        Settings → **Cascade** → **MCP servers**:

        ```json theme={null}
        {
          "pullstory": {
            "command": "npx",
            "args": ["-y", "@pullstory/mcp@latest"],
            "env": { "PULLSTORY_API_KEY": "${PULLSTORY_API_KEY}" }
          }
        }
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Restart">
    Close and reopen the client. Verify `pullstory` appears in your MCP server list.
  </Step>

  <Step title="Try it">
    Ask naturally:

    ```
    Make a video explaining how auth works in this repo
    ```
  </Step>
</Steps>

## Tools exposed

<ResponseField name="create_pull_story" type="tool">
  **Input:** structured brief with `title`, `summary`, `files`, optional `repo`, `flow`, and `highlights`
  **Output:** story ID, status, URL

  Triggers generation if an identical brief is not already cached.
</ResponseField>

<ResponseField name="get_pull_story" type="tool">
  **Input:** `id` returned by `create_pull_story` (`brief_<16-hex>`)
  **Output:** status (`generating` | `ready` | `failed` | `not_found`), URL, duration, scene count
</ResponseField>

## Security

* Keep your API key in your environment or password manager; do not commit raw `ps_live_...` values in project config
* The key is sent only by the MCP server when it calls the pull/story API directly
* The MCP server is [open source](https://github.com/EchoMosh) — you can audit exactly what it sends
* Revoke any key instantly from [pullstory.com/dashboard/api-keys](https://pullstory.com/dashboard/api-keys)

## Troubleshooting

<AccordionGroup>
  <Accordion title="MCP server doesn't start">
    Make sure you have Node 20+. The MCP server is a stdio process, so it stays open waiting for JSON-RPC messages when launched manually.
  </Accordion>

  <Accordion title="'Tool not found' in the agent">
    The MCP server is listed but tools aren't visible. Run `/mcp` (Claude Code) or restart the client. Some clients cache tool schemas.
  </Accordion>

  <Accordion title="'Unauthorized' on every call">
    Your API key is missing, wrong, or revoked. Check the value in your MCP config matches [pullstory.com/dashboard/api-keys](https://pullstory.com/dashboard/api-keys).
  </Accordion>
</AccordionGroup>