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

# Install the MCP server

> Connect Parlay to Claude Desktop, Cursor, Windsurf, Continue, Zed, Claude Code, or any custom MCP client.

The Parlay MCP server runs as a local subprocess via `npx`. **No global install required** — your AI client spawns a fresh `@goparlay/mcp-server` process per session.

## Before you start

You need:

* A Parlay API key (`pk_sandbox_…` or `pk_live_…`). [Get one](https://console.goparlay.io/signup) if you haven't already.
* Node.js 18+ installed on your machine (for `npx`).

That's it. No Bun, no Docker, no cloud deploy.

## Pick your client

<Tabs>
  <Tab title="Claude Desktop">
    Claude's desktop app reads MCP servers from a JSON config file.

    <Steps>
      <Step title="Open the config file">
        **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

        **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

        Create the file if it doesn't exist.
      </Step>

      <Step title="Add Parlay">
        ```json theme={null}
        {
          "mcpServers": {
            "parlay": {
              "command": "npx",
              "args": ["-y", "@goparlay/mcp-server@latest"],
              "env": {
                "PARLAY_API_KEY": "pk_sandbox_YOUR_KEY"
              }
            }
          }
        }
        ```

        If you already have other MCP servers, add `"parlay"` as a sibling key.
      </Step>

      <Step title="Restart Claude Desktop">
        Fully quit (`Cmd+Q` / `Ctrl+Q`) and reopen. Look for the tool icon in the conversation toolbar — you should see Parlay listed with 63 tools.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Cursor">
    Cursor uses the same MCP config format as Claude Desktop.

    <Steps>
      <Step title="Open MCP settings">
        `Cmd+Shift+P` (or `Ctrl+Shift+P`) → "Cursor Settings" → MCP tab → "Edit in settings.json"

        Or open `~/.cursor/mcp.json` directly.
      </Step>

      <Step title="Add Parlay">
        ```json theme={null}
        {
          "mcpServers": {
            "parlay": {
              "command": "npx",
              "args": ["-y", "@goparlay/mcp-server@latest"],
              "env": {
                "PARLAY_API_KEY": "pk_sandbox_YOUR_KEY"
              }
            }
          }
        }
        ```
      </Step>

      <Step title="Reload Cursor">
        `Cmd+Shift+P` → "Reload Window". Parlay tools become available in agent mode.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Windsurf">
    Windsurf supports MCP via its config file.

    <Steps>
      <Step title="Open Windsurf MCP config">
        `~/.codeium/windsurf/mcp_config.json`
      </Step>

      <Step title="Add Parlay">
        ```json theme={null}
        {
          "mcpServers": {
            "parlay": {
              "command": "npx",
              "args": ["-y", "@goparlay/mcp-server@latest"],
              "env": {
                "PARLAY_API_KEY": "pk_sandbox_YOUR_KEY"
              }
            }
          }
        }
        ```
      </Step>

      <Step title="Restart Windsurf">
        Fully quit and reopen. Parlay tools appear in Cascade.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Claude Code (CLI)">
    Claude Code lets you add MCP servers without editing JSON.

    ```bash theme={null}
    claude mcp add parlay \
      -e PARLAY_API_KEY=pk_sandbox_YOUR_KEY \
      -- npx -y @goparlay/mcp-server@latest
    ```

    Then start a session:

    ```bash theme={null}
    claude
    ```

    Verify it's loaded with `/mcp` inside the conversation. Parlay should appear with 63 tools.

    To remove later: `claude mcp remove parlay`.
  </Tab>

  <Tab title="Continue (VS Code / JetBrains)">
    [Continue](https://continue.dev) supports MCP servers via its config file.

    <Steps>
      <Step title="Open Continue config">
        `~/.continue/config.json`
      </Step>

      <Step title="Add Parlay under experimental.modelContextProtocolServers">
        ```json theme={null}
        {
          "experimental": {
            "modelContextProtocolServers": [
              {
                "transport": {
                  "type": "stdio",
                  "command": "npx",
                  "args": ["-y", "@goparlay/mcp-server@latest"],
                  "env": {
                    "PARLAY_API_KEY": "pk_sandbox_YOUR_KEY"
                  }
                }
              }
            ]
          }
        }
        ```
      </Step>

      <Step title="Reload your IDE">
        Continue picks up the change on next agent invocation.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Zed">
    Zed supports MCP servers as "context servers" in its config.

    <Steps>
      <Step title="Open Zed settings">
        `Cmd+,` → "Open settings.json"
      </Step>

      <Step title="Add Parlay under context_servers">
        ```json theme={null}
        {
          "context_servers": {
            "parlay": {
              "command": {
                "path": "npx",
                "args": ["-y", "@goparlay/mcp-server@latest"],
                "env": {
                  "PARLAY_API_KEY": "pk_sandbox_YOUR_KEY"
                }
              }
            }
          }
        }
        ```
      </Step>

      <Step title="Reload Zed">
        Settings auto-reload on save.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Anthropic SDK (TypeScript)">
    If you're building a custom agent with [`@anthropic-ai/sdk`](https://www.npmjs.com/package/@anthropic-ai/sdk), use the [`@modelcontextprotocol/sdk`](https://www.npmjs.com/package/@modelcontextprotocol/sdk) client to spawn Parlay's MCP server as a subprocess and forward tool calls.

    ```ts theme={null}
    import Anthropic from "@anthropic-ai/sdk";
    import { Client } from "@modelcontextprotocol/sdk/client/index.js";
    import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

    const transport = new StdioClientTransport({
      command: "npx",
      args: ["-y", "@goparlay/mcp-server@latest"],
      env: { ...process.env, PARLAY_API_KEY: process.env.PARLAY_API_KEY! },
    });

    const mcp = new Client({ name: "my-agent", version: "0.1.0" }, { capabilities: {} });
    await mcp.connect(transport);

    const { tools } = await mcp.listTools();
    const anthropic = new Anthropic();

    const response = await anthropic.messages.create({
      model: "claude-opus-4-7",
      max_tokens: 4096,
      tools: tools.map((t) => ({
        name: t.name,
        description: t.description ?? "",
        input_schema: t.inputSchema as Anthropic.Tool["input_schema"],
      })),
      messages: [{ role: "user", content: "Analyze mock://perfect-pitch under acme/alex." }],
    });

    // On each tool_use block in response.content, call mcp.callTool({ name, arguments }) and feed the result back.
    ```

    Loop the model + `mcp.callTool` until the model returns a final assistant turn.
  </Tab>

  <Tab title="Custom MCP client">
    If your client speaks the [MCP protocol](https://spec.modelcontextprotocol.io) directly, here's the canonical stdio invocation:

    ```bash theme={null}
    npx -y @goparlay/mcp-server@latest
    ```

    The process reads JSON-RPC requests on stdin and writes responses to stdout. Logs go to stderr (never stdout — stdout is reserved for protocol).

    **Required env:**

    * `PARLAY_API_KEY` — your Parlay key

    **Optional env:**

    * `PARLAY_MCP_LOG_LEVEL` — `debug`, `info` (default), `warn`, `error`
    * `PARLAY_API_BASE_URL` — **don't set this.** Defaults to `https://api.goparlay.io` (production), which is what you want for both sandbox and live keys. Sandbox keys (`pk_sandbox_…`) are gated by your API key prefix, not the URL — they bill at \$0 against test data on the same prod endpoint. Only override this for self-hosted Parlay deployments.

    Send `initialize`, then `notifications/initialized`, then any `tools/list` or `tools/call` request.
  </Tab>
</Tabs>

## Verify it's working

In your AI client, paste this:

```
Use parlay tools to ping the server and tell me which environment I'm connected to.
```

You should see something like:

```json theme={null}
{
  "pong": true,
  "echo": null,
  "timestamp": "2026-04-24T17:56:41.748Z",
  "base_url": "https://api.goparlay.io",
  "key_environment": "sandbox",
  "server": "@goparlay/mcp-server@0.1.0"
}
```

If `key_environment: "sandbox"` matches the prefix of your key, you're good.

## Environment variables reference

| Variable               | Required | Default                   | Notes                                                                                                                                                                                                                                                                                                    |
| ---------------------- | -------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PARLAY_API_KEY`       | yes      | —                         | Your Parlay key (`pk_sandbox_…` or `pk_live_…`)                                                                                                                                                                                                                                                          |
| `PARLAY_MCP_LOG_LEVEL` | no       | `info`                    | `debug` for full request/response logs                                                                                                                                                                                                                                                                   |
| `PARLAY_API_BASE_URL`  | no       | `https://api.goparlay.io` | **Don't set this.** Sandbox vs live is determined by your API key prefix, not by URL. Override only for self-hosted Parlay or internal staging. The MCP refuses to start if you pair a `pk_live_*` key with a known dev URL — protects you from accidentally sending live traffic to a non-prod cluster. |

<Callout type="warning">
  **Common pitfall — don't set `PARLAY_API_BASE_URL`.** Older config snippets
  online may show this pointing at a Vercel preview URL or `parlay-api-dev`.
  Those are stale. The default (production) is correct for everyone.
</Callout>

## Troubleshooting

<AccordionGroup>
  <Accordion title="The Parlay server shows red / not running">
    Open your client's MCP logs (Claude Desktop: `~/Library/Logs/Claude/mcp-server-parlay.log`). Common causes:

    * `PARLAY_API_KEY is not set` — env block isn't reaching the subprocess. Double-check the JSON config.
    * `Cannot find module @goparlay/mcp-server` — npx couldn't resolve the package. Run `npx -y @goparlay/mcp-server@latest --help` from a terminal to verify it works standalone.
    * `npx: command not found` — install [Node.js 18+](https://nodejs.org).
  </Accordion>

  <Accordion title="Tools appear but every call fails with `authentication_required`">
    Your key is invalid or expired. Test with:

    ```bash theme={null}
    curl https://api.goparlay.io/v1/personas \
      -H "Authorization: Bearer YOUR_KEY"
    ```

    If that returns `401`, regenerate your key.
  </Accordion>

  <Accordion title="Tool calls hang for minutes">
    Async tools (`analyze_recording`, `assign_rep_persona`, etc.) wait for the AI job to complete. Real audio takes 30–90 seconds. Mock fixtures should be near-instant — if they hang, your key may not have access to the right environment.
  </Accordion>

  <Accordion title="I'm using a corporate proxy / firewall">
    The MCP server makes outbound HTTPS calls to `api.goparlay.io`. Whitelist that domain (or your live equivalent). The MCP server reads `HTTPS_PROXY` from the environment if set.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Tool catalog" icon="list" href="/mcp/tool-catalog">
    All 63 tools, what they do, when to use which
  </Card>

  <Card title="Examples" icon="lightbulb" href="/mcp/examples">
    Paste-ready prompts that demonstrate real workflows
  </Card>
</CardGroup>