--- title: "Use the Perspective AI MCP" nav_title: "MCP Integration" description: "Connect Perspective to Claude Code, Cursor, VS Code, and other MCP clients via OAuth or a workspace-scoped key to create agents, analyze conversations, read insights, and deploy embeds from your AI assistant." date: "2026-07-13" tags: ["MCP server", "AI assistant integration", "Claude integration", "developer tools", "OAuth"] nav_order: 1 nav_display: true --- # Use the Perspective AI MCP Server The Perspective AI MCP (Model Context Protocol) Server connects your Perspective workspace to AI assistants like Claude Desktop, Claude Code, and Cursor. Once configured, you can create conversation agents, check project status, analyze conversations (stats, search, deep exploration), read analyst insights, and deploy embeds without leaving your development environment. ## What You Can Do With the MCP server connected, you can: - **Create conversation agents** directly in your AI assistant without switching to the Perspective dashboard - **Check project status** — phase (design / test / share / live), completion rates, credits, and automation rollup - **Read analyst insights** — list published or draft insights, then pull full content by id - **Analyze conversations** with quantitative pipelines, semantic search, or deep transcript exploration - **Compare across multiple perspectives** to identify patterns and themes across research projects - **Deploy embeds from your editor** by generating and inserting embed code directly into your codebase ## Prerequisites - A Perspective AI workspace - One of these AI assistants: - Claude.ai (web, with custom connector support) - Claude Desktop - Claude Code (command-line tool) - Cursor IDE - VS Code (with MCP support) ## Connect via OAuth OAuth is the recommended path: you add the Perspective MCP URL to your client, complete a one-time browser sign-in, and the client manages the connection from there. No tokens to copy, rotate, or store in config files. Every connected app shows up under **Connected Apps** in Settings, where you can revoke access anytime. Open the workspace switcher and choose **Manage workspace** to reach Settings. The MCP URL is the same for everyone: ``` https://getperspective.ai/mcp ``` ### Claude.ai (web) Open the [Add custom connector](https://claude.ai/settings/connectors?modal=add-custom-connector) dialog (or navigate manually: **Customize > Connectors > Add custom connector**) and fill in: - **Name**: `Perspective AI` - **Remote MCP server URL**: `https://getperspective.ai/mcp` Click **Add**, then complete OAuth in the browser when prompted. The connector becomes available to every chat in your workspace. See [Anthropic's custom connector guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) for details. ### Claude Code ```bash claude mcp add --transport http --scope user perspective https://getperspective.ai/mcp ``` The first time you call a Perspective tool, Claude Code opens a browser window to complete OAuth. `--scope user` makes Perspective available across all your projects — without it, Claude Code only loads the server in the directory where you ran the command. ### Claude Desktop Claude Desktop doesn't speak HTTP MCP natively. Use the [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) shim, which handles the OAuth handshake in your browser. Add this to your Claude Desktop config file: ```json { "mcpServers": { "perspective": { "command": "npx", "args": ["mcp-remote", "https://getperspective.ai/mcp"] } } } ``` Restart Claude Desktop and trigger a Perspective request to start OAuth. ### Cursor Add this to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project): ```json { "mcpServers": { "perspective": { "type": "http", "url": "https://getperspective.ai/mcp" } } } ``` Trigger a Perspective request and complete the browser sign-in. ### VS Code Open **MCP: Open User Configuration** from the Command Palette to edit your user `mcp.json`, or create `.vscode/mcp.json` to share with your team: ```json { "servers": { "perspective": { "type": "http", "url": "https://getperspective.ai/mcp" } } } ``` VS Code uses `servers` at the top level, not `mcpServers`. Trigger a Perspective request and complete the browser sign-in. ### Other stdio-only clients For MCP clients that only speak stdio, use the `mcp-remote` shim. It discovers OAuth metadata automatically: ```json { "mcpServers": { "perspective": { "command": "npx", "args": ["mcp-remote", "https://getperspective.ai/mcp"] } } } ``` ## Connect with a Workspace-Scoped Key If your client doesn't support OAuth or you'd rather authenticate with a long-lived credential, create an MCP key and use its token as a bearer token. ### 1. Create an MCP Key Open the profile menu at the bottom of the sidebar and choose **MCP**, or open the workspace switcher, choose **Manage workspace**, and select **MCP**. Under **Create a new key**, enter a name, select the workspaces the key may access, and click **Create key**. Each key is **scoped to the workspaces you select** — an assistant using it can only reach those workspaces, and only while you remain a member of them. Create a separate key per assistant, scoped to just the workspaces that client needs. ![MCP page showing the Create a new key form](/images/generate-mcp-token.gif "screenshot") *Create a workspace-scoped key to enable MCP integration.* Once created, Perspective shows the full token once in a secure dialog. Copy it before closing the dialog; after that, the key list only shows a masked token. If you lose the token, delete the key and create a replacement. ![MCP key card showing the token and configuration options](/images/ai-ide-options.png "screenshot") *Copy the configuration details for your AI assistant.* MCP keys work with the MCP endpoint and with the current REST create endpoint. OAuth access tokens are scoped to the remote MCP resource and should be used only with `/mcp`. ### 2. Configure Your AI Assistant #### Claude Code ```bash claude mcp add --transport http --scope user perspective https://getperspective.ai/mcp \ --header "Authorization: Bearer [your-token]" ``` `--scope user` makes Perspective available across all your projects. #### Claude Desktop Add this to your Claude Desktop config file: ```json { "mcpServers": { "perspective": { "command": "npx", "args": [ "mcp-remote", "https://getperspective.ai/mcp", "--header", "Authorization: Bearer [your-token]" ] } } } ``` #### Cursor Add this to `~/.cursor/mcp.json`: ```json { "mcpServers": { "perspective": { "type": "http", "url": "https://getperspective.ai/mcp", "headers": { "Authorization": "Bearer [your-token]" } } } } ``` #### VS Code Add this to your user `mcp.json` (Command Palette → **MCP: Open User Configuration**) or to `.vscode/mcp.json` in a project: ```json { "servers": { "perspective": { "type": "http", "url": "https://getperspective.ai/mcp", "headers": { "Authorization": "Bearer [your-token]" } } } } ``` ### 3. Verify the Connection Open your AI assistant and try a Perspective-related request, such as "Create a new interview outline for user feedback on our pricing page." If configured correctly, your assistant will connect to Perspective and execute the request. ## Tool Coverage The MCP server exposes tools across the same product areas you use in the dashboard: | Family | Example tools | What they do | |--------|---------------|--------------| | Workspace | `workspace_list`, `workspace_get`, `workspace_get_default` | Find the right workspace and inspect workspace details. | | Perspective design | `perspective_create`, `perspective_respond`, `perspective_update`, `perspective_await_job` | Create a draft, answer design follow-ups, and revise an existing outline. | | Deployment | `perspective_get_preview_link`, `perspective_get_embed_options` | Generate preview links, share/direct URLs, and embed snippets. | | Status & insights | `read_perspective_status`, `read_insights`, `read_insight` | Check how a project is progressing; list analyst insights and open full insight content. | | Results | `perspective_get_stats`, `perspective_list_conversations`, `perspective_get_conversation`, `perspective_get_conversations` | Inspect stats, browse responses, and pull summaries or transcripts. | | Conversation analysis | `conversations_data_analysis`, `conversations_search`, `conversations_explorer` | Counts and trends, theme search across conversations, and deeper transcript exploration. | | Participants | `participant_invite` | Create 48-hour magic links, reissue invite links, optionally send invite emails, and attach participant context. | | Automations | `automation_list`, `automation_create`, `automation_update`, `automation_delete`, `automation_test` | Manage per-interview and scheduled automations, then test delivery. | | Integrations | `integration_manage` | List connected providers, open setup URLs, and discover Slack, HubSpot, or Gmail tool slugs for automation channels. | | Slack channels | `slack_channel_search`, `slack_channel_resolve`, `slack_channel_refresh`, `slack_channel_refresh_status` | Find and verify Slack channels to use as automation targets, and refresh the channel directory from Slack. | ### Analysis tools at a glance | Tool | Use when | |------|----------| | `read_perspective_status` | You want a quick health check — progress, volume, credits, automations. | | `read_insights` / `read_insight` | You want existing analyst findings listed, then the full content of one. | | `conversations_data_analysis` | You need counts, breakdowns, or trends across conversations. | | `conversations_search` | You want themes, sentiment, or “what do people say about X?” | | `conversations_explorer` | You need deeper exploration of conversation text (exact phrases, comparisons, close reads). | | `perspective_await_job` | Design or exploration is still running and your assistant needs to wait for the result. | For embed-specific implementation details, see the [Embed API Reference](/docs/build/embed-api). For webhook payloads and retry behavior, see [Webhooks](/docs/build/webhooks). ## Example Workflows **Create a conversation agent from your IDE:** Ask your AI assistant: "Create a new interview outline for customer discovery on our mobile app usage patterns." **Check status before analyzing:** Ask: "What's the status of the Q1 churn research perspective — progress, completion rate, and any insights already published?" **Analyze conversations during development:** Ask: "Search conversations in the Q3 user research outline for onboarding frustrations and summarize the top themes with quotes." **Quantitative breakdown:** Ask: "From the pricing-page lead qualification perspective, break down qualified vs not by referral source." **Deep transcript exploration:** Ask: "Find exact mentions of 'switching costs' across completed conversations in the enterprise churn study." **Compare across research projects:** Ask: "Analyze conversations from both the onboarding outline and the pricing outline. What themes appear in both?" **Deploy an embed while coding:** Ask: "Generate the inline embed code for the product feedback outline and add it to the pricing page component." ## Best Practices - **Keep keys secure**: Treat a key's token like a password. To rotate it, delete the key and create a new one. - **Scope keys narrowly**: Give each key only the workspaces the client actually needs, so a leaked key has a limited blast radius. - **Use specific perspective names**: When referencing perspectives in requests, use exact names so your assistant targets the right project. - **Pick the right analysis tool**: Start with status or existing insights when available; use data analysis for counts, search for themes, and explorer when you need a closer read of the transcripts. - **Test with simple requests first**: Verify the connection works by listing workspaces or fetching stats before running complex analysis. ## Common Pitfalls & Fixes ### AI assistant returns "unable to connect to Perspective" Verify the key still exists on the MCP settings page. Check that you copied the full authorization header including the `Bearer` prefix. ### Assistant can't see a workspace The key isn't scoped to that workspace, or you've since left it. Create (or recreate) a key that includes the workspace you're targeting — keys only reach the workspaces they were granted, even for admins. ### Assistant creates duplicate outlines Be specific in your requests. Instead of "create an outline," say "check if an outline named [name] exists, and if not, create it." ### Key shows "Never" under "Last used" This updates after the first successful request authenticated with an MCP key. OAuth-connected clients appear under **Connected Apps** in Settings instead.