@goparlay/mcp-server

Official Model Context Protocol server for the Parlay API. Lets AI-native clients — Claude Desktop, Cursor, Windsurf, Claude Code, Continue, Zed, custom agents — call Parlay conversationally.

"Analyze this call: https://my-cdn.com/call.mp3. Rep is alex-smith in acme-corp. Once it's done, ask Scout where Alex needs the most help."

The model calls analyze_recording → polls until complete → calls ask_scout_about_call. All in one paragraph of natural language. No partner-side code.

63 conversational tools across 10 domains: analyses, orgs, reps, rep intelligence, Scout chat, playbooks, custom prompts, dispositions, org insights, webhooks, reference data — plus live documentation search (no separate docs MCP needed).

Install

Add to your AI client's MCP config — no global install required, runs via npx.

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (Mac) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "parlay": {
      "command": "npx",
      "args": ["-y", "@goparlay/mcp-server@latest"],
      "env": {
        "PARLAY_API_KEY": "pk_sandbox_..."
      }
    }
  }
}

Restart Claude Desktop. Parlay's tools appear in the tool picker.

Cursor / Windsurf / Continue / Zed

Same config block, different file:

| Client | Path | |---|---| | Cursor | ~/.cursor/mcp.json | | Windsurf | ~/.codeium/windsurf/mcp_config.json | | Continue | ~/.continue/config.json (under experimental.modelContextProtocolServers) | | Zed | settings.json under context_servers |

Full per-client install instructions: docs.goparlay.io/mcp/installation.

Claude Code (CLI)

claude mcp add parlay -e PARLAY_API_KEY=pk_sandbox_... -- npx -y @goparlay/mcp-server@latest

Get an API key

Sign up at the Parlay developer dashboard — sandbox keys are free and bill at $0 against test data. Use mock URLs (mock://perfect-pitch, etc.) for deterministic, near-instant testing.

Verify it's working

In your AI client, ask:

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

You should see:

{
  "pong": true,
  "key_environment": "sandbox",
  "base_url": "https://api.goparlay.io",
  "server": "@goparlay/[email protected]"
}

If key_environment matches your key prefix, you're done.

Environment variables

| Variable | Required | Default | Notes | |---|---|---|---| | PARLAY_API_KEY | yes | — | Your Parlay key (pk_sandbox_... or pk_live_...) | | PARLAY_MCP_LOG_LEVEL | no | info | debug, info, warn, error | | PARLAY_API_BASE_URL | no | https://api.goparlay.io | Don't set this. Sandbox vs live is determined by your key prefix, not the URL — sandbox keys bill at $0 against test data on the same prod endpoint. Override only for self-hosted deployments. The MCP hard-fails if a pk_live_* key is paired with a known dev URL. |

What you can do

A few prompts to try in Claude / Cursor:

Submit mock://perfect-pitch under org "demo" rep "alex-smith".
Wait for results and tell me the overall score.

Generate a coaching synthesis for rep alex-smith using their last 5 calls.
Show me the top gap and this-week action plan.

Upload these two source documents [paste], then generate a playbook draft
from both. Show me the first 500 chars and publish it.

Show me the top 5 reps in demo by score this month. Then by improvement.
Tell me who appears on both lists.

Register a webhook at https://my-app.com/parlay-hook for analysis.completed.
Send a test event to confirm it works.

More examples →

Tool catalog

60+ tools grouped by domain. Each tool's description includes its latency + cost. Read endpoints are free; AI operations bill against your key.

| Domain | Examples | |---|---| | Analyses | analyze_recording, get_analysis, list_analyses | | Orgs & Reps | create_or_update_org, create_or_update_rep, get_rep_stats | | Rep intelligence | assign_rep_persona, assign_rep_methodology, generate_rep_synthesis | | Scout chat | ask_scout_about_call, get_scout_welcome_questions | | Playbooks | create_playbook, generate_playbook_draft, publish_playbook_draft | | Custom prompts | create_custom_prompt, reorder_custom_prompts | | Dispositions | tag_disposition, list_dispositions | | Org insights | generate_org_insights, get_leaderboard | | Webhooks | register_webhook, test_webhook, rotate_webhook_secret | | Reference data | list_personas, list_methodologies | | Documentation | search_parlay_docs, read_parlay_doc, list_parlay_docs |

Full catalog →

How it works

The MCP server is stateless. It runs on your machine via npx, holds no data, and forwards every call to Parlay's REST API over HTTPS. Same auth, same data, same SLAs as direct REST integration.

Async endpoints (analyze_recording, assign_rep_persona, generate_playbook_draft, generate_org_insights) are polled internally — your model sees a synchronous response. Per-tool timeouts are tuned to typical job latency.

Troubleshooting

• PARLAY_API_KEY is not set — env block isn't reaching the subprocess. Double-check the JSON config.
• authentication_required on every call — your key is invalid or expired. Test with curl https://api.goparlay.io/v1/personas -H "Authorization: Bearer YOUR_KEY".
• Tool calls hang — async tools wait for AI jobs to complete. Real audio: 30–90s. Mock fixtures: under 1s.
• Behind a corporate proxy — set HTTPS_PROXY env var.

Full troubleshooting: docs.goparlay.io/mcp/installation.

Documentation

• Quickstart: docs.goparlay.io/quickstart
• MCP install (8 client tabs): docs.goparlay.io/mcp/installation
• Tool catalog: docs.goparlay.io/mcp/tool-catalog
• API reference: docs.goparlay.io/api-reference

Security

• Never commit your API key. pk_live_* keys grant full production access. Pass via the MCP client's env block (Claude Desktop, Claude Code, Cursor, etc.) or your shell — never via a tracked config file.
• Rotate keys through console.goparlay.io/dashboard/keys if a key is exposed (laptop loss, accidental commit, paste in Slack).
• Use sandbox keys for development. pk_sandbox_* keys can only submit mock:// fixtures and never bill against your account.
• This package runs locally with your full filesystem access — only install from the official @goparlay/mcp-server scope on npm. Do not run forks or pinned older versions without reviewing their source.
• Reporting a vulnerability: email [email protected]. We follow RFC 9116 — see https://console.goparlay.io/.well-known/security.txt.

License

Proprietary. See LICENSE. Use of this package requires a valid Parlay API key. Contact [email protected] for licensing inquiries.