Model Context Protocol (MCP) Integration

The Model Context Protocol (MCP) integration connects AI assistants and code editors to your Deck organization so they can use Deck's vertical product-decision context — insights, themes, Competitors intelligence, and scoped Build workflows — during conversations or while coding. This is not a generic "chat with your feedback" layer; it supplies the structured product signal a generalist agent lacks.

Supported clients: Claude Desktop, Claude Code, ChatGPT, Cursor, VS Code, Windsurf, Zed, Codex, Gemini CLI, Grok Build, Lovable, Muse by Meta, and v0 by Vercel.

What is MCP?

Model Context Protocol is an open standard introduced by Anthropic that enables AI assistants to securely connect to external data sources. MCP provides a universal interface for AI systems to read data, execute functions, and handle contextual prompts. The protocol has been adopted by major AI providers including OpenAI and is now managed by the Agentic AI Foundation under the Linux Foundation.

Deck's MCP server provides a secure OAuth interface for AI assistants to query your customer feedback data, Competitors intelligence, and execute bounded Build or Competitors actions that you explicitly request.

Coding agents should follow the agent prompt library rather than inventing a signup or API-key path. Signup-wired protocols are AI PM and Competitors. Other keys are MCP runbooks that bounce to the AI PM protocol if Deck MCP tools are missing.

Features

The Deck MCP server provides 31 intent-based tools that give AI assistants access to your feedback data, customer segments, Competitors intelligence, SDK feedback widgets, and selected Build actions, plus a visual Deck view for ChatGPT and other clients that support MCP Apps. One of the 31 tools, submit_feedback, sends feedback about Deck to the Deck team.

Overview & Context

• get_overview - Get a complete snapshot of your feedback landscape: organization context, data counts, top themes, and recent activity. When your organization has customer segments enabled, also returns the list of available segments so the AI can offer segment-filtered analysis. NPS figures are included only on the Starter plan or higher: the NPS shown on the NPS page (rolling 30 days, or the latest weekly synthesis when there are no recent responses) and the all-time score.
• get_user_context - Identify who is connected so the AI can personalize its responses.
• select_organization - Choose which Deck organization the AI should use when your account belongs to more than one organization.
• explore_workspace - List the members of your organization with their user IDs, names, emails and roles (admin or member), and which one is you. The AI uses a member's user ID to filter Projects and initiatives by owner or to set a Project owner. With view=settings, it shows which features are on, which roles can use MCP and the Public API and, for admins, whether PII redaction is on. It never returns API keys. With view=credits, it shows your plan, the credits left this period, the credit warning level and the items that wait for credits. Admins also get a link to Billing settings. It never returns invoices or payment details.
• explore_segments - List your customer segments with their insight counts, number of rules, top theme and sentiment, with a link to Settings > Segments. Give a segment ID to see that segment's rules and which rules are active. Give preview_rule to see a sample of the existing insights a rule would tag, before you save it. If segments are off, it says an organization admin can turn them on in Settings > Segments.
• mutate_segments - Create a segment, change its name, color, description or position, or archive it; add, change or delete a segment rule; set the manual segments of every insight from one feedback source; confirm an AI segment assignment; turn segments on or off for the workspace. Any organization member can use it, except set_enabled, which only organization admins can use. After a rule is added or a matching field is changed, Deck re-tags existing insights in the background. Changing only a rule's priority does not re-tag. Archive and delete cannot be undone through MCP.
• get_platform_links - Get Deck web app links for up to 20 themes, subthemes, insights, interviews, the NPS dashboard, initiatives, opportunities, projects, the Competitors page, or a Settings page in one call. Without an ID, the link opens the list view (not available for insights and subthemes). A Settings link needs the page name, for example security for your password, passkeys and account deletion, which you change in the browser (the AI never asks for your password), or api_access for API keys. No MCP tool returns a full key. Links to the Organization, Billing, Context, Privacy and Reindexing pages are marked admin_only because only organization admins can open them. Most tools already include a deck_url, so the AI uses this mainly for batches or for IDs that came without a link. When you paste a Deck link, the AI sends it as urls (up to 20) and gets back what the page shows (for example a theme and its ID, with any segment filter) and the tool to call next. Deck never opens the URL. A link to another workspace returns no IDs, and a Settings link only tells the AI which page it is, because you change settings in the browser.

Themes & Subthemes

• explore_themes - Browse all feedback themes or drill into a specific theme to see sentiment breakdowns, category distributions, and associated insights. When your organization uses customer segments, you can scope the theme list and a theme's stats to up to 20 segments, and include or exclude them. Each theme's count then covers only that feedback. When you exclude segments, a single theme shows its stats only, as on the Deck theme page; the AI can then list those insights with explore_insights. Results say which segments Deck applied. The theme list can show priority views (highest negative share, surging themes, most feature requests), sort by insight count, name or latest insight, filter by sentiment share or recent activity, and page through every theme. The surging view says no themes are surging when the top theme's recent count is not higher than the 14 days before. To find a theme by a word, the AI can pass a query: Deck returns only the themes whose name or notes match, most insights first. Each theme shows its sentiment shares, feature requests and surge stats. The categories view answers "what drives our bugs or feature requests?" in one call, as on the Deck Categories page: it shows how many insights each category has, with its top themes, or, for one category, every theme with its count and percent of the theme.
• explore_subthemes - Explore AI-detected subthemes within your feedback. List all subthemes across themes, filter by a specific theme or by one or more customer segments, read the all-customer subthemes, keep only subthemes with feedback in the last 7, 30, 90, 180 or 365 days (counts stay all-time), or drill into a single pattern to see its synthesis narrative, key quotes, sentiment timeline, and related subthemes. A small subtheme shows its quotes inline. With view=insights the AI reads up to 100 of a subtheme's insights with quotes per call, sorted and filtered by sentiment, and with view=uncategorized it reads the theme's insights that are not in a subtheme yet. Your organization's PII setting can mask quotes and emails. Sort the list by most insights (default), trending, highest negative share, latest insight, or sudden changes, and group it by theme with theme totals. Each subtheme shows the trend Deck computes for the last 14 days against the 14 days before, so the AI quotes Deck's numbers instead of computing its own. With a theme filter, the AI also sees how many of the theme's insights are not in a subtheme yet, and whether the theme needs more insights before Deck builds subthemes. Each list says which segments and window Deck applied, and says so when the chosen segments have no segment-level subthemes yet and Deck shows the all-customer subthemes instead.

Insights & Search

• explore_insights - Search for specific feedback by keyword, browse recent insights by time window (e.g., last 24 hours or last 7 days, at most 30 days), filter by sentiment or category, or get full details on a specific insight including quotes, video snippets, the customer, the interview date and the original source (for example the support ticket with its first messages, the Slack message or the survey answer) with a link to it in Deck. Supports filtering by customer segment across all modes. The list and keyword search also take several segments (include or exclude them) and a window of the last 7, 30, 90, 180 or 365 days or a date range. The date is when the customer said it: the interview date, else the import date. Results say which segments and window Deck applied.
• search_deck - Find anything in Deck by one keyword: insights, themes, subthemes, interviews, initiatives, projects, and opportunities, grouped by type. Without a keyword, it shows the most recently updated items of each type. Each result has a link to the Deck web app and the tool call that opens it. Subtheme results need the Starter plan or higher.

Transcripts & Sources

• read_transcript - Read any feedback source and the insights extracted from it. Interviews, sales calls and CSV or Notion interview rows return the transcript with speaker segments and timestamps. Intercom and Zendesk tickets return the ticket thread, Slack the message, surveys the answer and other CSV rows their columns. Widget feedback returns the source details and insights, with no transcript when the source has none. Each insight shows its themes and where its quote is in the transcript. The result also shows the processing status (complete, processing, failed or out of credits) and a link to the source in Deck, where the recording plays. Long transcripts and ticket threads come in pages. Every source ID from list_sources or an insight works. Deck does not store app reviews, so there is no app-review source type.
• list_sources - See all feedback sources in your organization, newest first: interviews, sales calls, support tickets, surveys, Slack messages, email, product analytics events, and feedback from the in-app feedback widget. Filter by type, processing status, where the source came from (for example Gong, Slack, Zendesk, Notion or CSV), name, segment, created date, Slack channel and support ticket state, and sort by date, interview date, name or insight count, all in the same call. Each source shows its interview date, email, segment, themes and insight count, and support tickets show their subject, state and requester. Sorting by name orders widget feedback by the message, not the sender. Pass up to 50 feedback IDs to check whether those sources finished processing and, when one failed, why. Set synthesized to false with Intercom, Zendesk or Custom API as the source to see support tickets that synced but are not yet processed into feedback. Set import_source to NOTION or CSV to see your Notion imports or CSV uploads, then pass an upload_id to see the rows of one upload, each with a feedback ID that read_transcript can read.
• explore_integrations - See which of the 12 integrations are connected, which need attention and which your plan does not allow yet, with a link to each one in Settings. Ask about one integration to get its features, docs link and connection steps. Ask for the Slack channels to see which channels Deck syncs, which need the Deck bot (/invite Deck) and which an admin can add. Connecting an integration or adding a Slack channel happens in Settings → Integrations, and only organization admins can manage integrations.

Feedback Widgets

• list_widgets - See the SDK feedback widgets of your organization: name, status (active or archived), linked Project, and how much feedback each one received. Active widgets show by default.
• explore_widgets - Open one widget, active or archived: feedback counts by synthesis status, the 10 most recent submissions, your organization's active publishable keys as masked prefixes, a link to Settings → Deck Collect SDK, and a prompt that a coding agent can use to install the SDK for this widget.
• mutate_widgets - Create a widget, rename it, link it to a Project or unlink it, or archive it. Archive cannot be undone: the widget stops accepting feedback, and the feedback it already received stays in Deck.

NPS Analysis

• explore_nps - Deep-dive into your Net Promoter Score data. Get an overall summary, drill into promoters, passives, or detractors, explore score trends over time (the same 30-day rolling series as the NPS page, weekly respondent shares and the themes behind a rise), get AI-generated recommendations for improvement, look up a specific NPS response by ID, or list responses one page at a time with filters (score band, respondent type, theme, text, sentiment, period, segments) and the insight each response is linked to. Listed responses show no respondent name or email.

Competitors

• explore_competitors - Browse your competitor landscape, open one competitor, list the strengths, weaknesses and other subthemes (view=subthemes with an optional group), inspect a subtheme, list competitor synthesis insights (view=insights or insight_id), list opportunity teasers, poll a research job, inspect check-in history and the check-in schedule (view=checkins or view=latest_checkin), or read the Competitors settings (view=settings: the review sources, the most credits one research run can use, the free window, plan limits, whether research is running and the check-in schedule). view=insights treats competitor, subtheme, and teaser IDs as list filters, not detail shortcuts. With competitor_id, view=subthemes, view=teasers and a subtheme show only that competitor, and the link opens that competitor's tab. Insight pages default to 50 results and cap at 100. Quotes from Reddit and LinkedIn can include the parent post and whether the quote is a post, comment, or reply. There is no source-type filter — the assistant reads those fields on each quote. With no parameters it also returns suggested_competitors: the direct competitors Deck found for your company when you signed up with a work email (empty otherwise). If Competitors is off for the workspace, the tool returns guidance instead of a hard error.
• mutate_competitors - Start research, add a competitor (merge-append onto the graph you already have), promote a subtheme, teaser, or set of competitor synthesis insights onto Opportunity Backlog, assign more competitor insights onto an existing backlog item, or — if you are an organization admin — enable periodic check-ins (set_checkins). Start research takes 1–25 competitors with websites, plus optional company_domain (your own company's website) and company_name. Pass your website when you signed up with a personal email, or Deck cannot tell which company the research is for. Research runs in the background; Deck emails you when it is ready. If a write fails, the assistant gets a plain sentence explaining why. While research is running, start_research and add_competitor return CONFLICT. Members cannot change the check-in schedule.

Build Workflows

• list_initiatives - Browse or search initiatives by title, status, owner, customer segment, or associated Project.
• explore_build_initiatives - Open one initiative by ID with document sections, evidence provenance, linked insights, and associated Projects. The detail includes Project status counts (not started, in progress, completed) and each Project's Jira or Linear link.
• list_projects - Browse or search Projects by title, status, owner, unassigned owner, customer segment, initiative, planning dates, a date the Project is active on, Jira/Linear metadata, evidence text, or linked opportunity context. A Project with a start date and no target date is active only on that start date. An empty filtered list names the filters that were set. Each row shows its evidence count and latest Jira or Linear link. With importable_from set to linear or jira, it lists the Linear projects or initiatives, or Jira epics, that you can import into Deck instead, one page at a time.
• explore_build_projects - Open one Project by ID. Project detail includes the description, segments, document sections, evidence references, generated story provenance, external links, parent initiative context, and Deck URLs.
• explore_opportunity_backlog - Review the current opportunity backlog or open a specific opportunity with evidence, linked initiatives, and linked Projects. By default the list shows what the Deck Backlog page shows: items with at least 3 pieces of evidence, in rank order. Earlier versions returned every item, so the default list is now shorter. Set min_evidence to 0 to get every item. One opportunity also returns Deck's brief (impact score out of 10, sentiment, trend, confidence, evidence counts and risk signals) and, for an opportunity promoted from Competitors, whether Deck agents are still matching your own feedback to it.
• mutate_initiative_build - Create an initiative (optionally with 1-100 insights as evidence), update its title or goal, change status, update the overview, evidence or outcomes section, assign customer segments, add 1-100 insights as evidence to an existing initiative, or import a Linear initiative with its child projects (import_from_linear, admins only).
• mutate_opportunity_build - Create an opportunity from insights (create; it saves right away, so in clients that show Deck views prefer create_from_insights), archive an opportunity, assign segments, link an initiative, create an initiative from an opportunity, or link existing insights, themes, or subthemes to it as evidence (assign_evidence).
• mutate_project_build - Create a Project, update its title, status, owner, or target date, archive it, link it to an initiative or detach it with initiative_id: null, update document sections with editor block nodes, link or unlink existing Jira/Linear artifact metadata, assign or unassign insights, generate an Evidence story from linked insights, replace its segments, or import a Linear project or Jira epic as a new Project (import_from_provider). Imports read Linear or Jira and create Deck records only.
• create_from_insights - Create an opportunity, Project, or initiative from your Deck insights, or add them to an opportunity you already have. You can name a customer pain point from a Deck view answer, and Deck attaches that pain point's insights as evidence. When the assistant uses this tool, nothing is saved yet: Deck's review opens in a Deck view, filled in, and Deck creates only when you click Create there. In an assistant without the Deck view, use the link it gives you to create in Deck. Creating uses no credits.

The Build list tools are designed for discovery. Use them when you know a human label, such as an owner name, segment name, status label, Project date state, or external Jira/Linear reference. Use the corresponding explore_build_* tool after the AI has selected a specific ID.

Mutation tools are intentionally narrow. They do not generate backlog stories, delete arbitrary records, create third-party Jira or Linear artifacts, or perform broad admin changes. create_from_insights only adds: it creates records and attaches evidence, starts no AI generation, and never archives, edits, or deletes anything. Competitor mutations start research, add a competitor, promote an existing finding (including a set of competitor synthesis insights), assign competitor insights onto a backlog item, or (admins only) set the check-in schedule. Enabling or disabling Competitors and deleting a tracked competitor stay in Settings → Competitors.

Visual Deck View

• show_deck_view - Show Deck data as an interactive view inside the conversation instead of plain text: KPIs, customer pain points, theme tables, a theme or subtheme breakdown, customer quotes with interview clips, NPS, segments, the opportunity backlog, Projects, and initiatives. The AI picks what to show; Deck loads every number, quote, and label itself, so the view always reflects your real data. Called with no options, it shows your Deck home view. From a customer pain point, the view can create an opportunity, Project, or initiative with that pain point's insights attached, or add the insights to a related opportunity, after you review the draft. It never deletes or archives anything. To change existing Projects, initiatives, or opportunities, ask the assistant in chat.

The Deck view renders in clients that support MCP Apps, such as ChatGPT. Other clients receive the same facts as text. See Deck view in ChatGPT.

Feedback about Deck

• submit_feedback - Send feedback about Deck itself to the Deck team: a bug, a wrong or confusing result, or a missing capability. The assistant can add the name and request_id of a related Deck tool call. When no Deck tool can do what you asked, the assistant sends a feature request with this tool before it tells you. The feedback goes into Deck's own workspace, not into yours, and it does not appear in your Deck data. With the message, Deck sends your user ID, email address, and name, your organization ID, and which AI client sent it (its user agent and OAuth client ID), so the Deck team can follow up. This tool is not for your customers' feedback: to collect that, use a feedback widget or an integration.

Tool reference

Each tool has one of three classifications:

• Read - Only reads data. MCP annotations: readOnlyHint: true, destructiveHint: false, openWorldHint: false.
• Write - Creates or changes records in Deck. It does not send email, spend credits, or archive anything in a way MCP cannot undo. A tool that both reads and writes counts as a Write.
  • create_from_insights only adds records and evidence, and saves only when you click Create in Deck's review. MCP annotations: readOnlyHint: false, destructiveHint: false, openWorldHint: false.
  • mutate_initiative_build can set an initiative's status to archived, but another update_status call can set it back (see the 24-hour replay rule in Write responses and retries), so it is a Write. It can also overwrite an initiative's title, goal, or sections and replace its segments, so its MCP annotations are readOnlyHint: false, destructiveHint: true, openWorldHint: true (import_from_linear reads your connected Linear workspace), and your AI client may ask for your approval before it runs.
  • submit_feedback adds one feedback record to Deck's own workspace, not to yours. Its MCP annotations are readOnlyHint: false, destructiveHint: false, openWorldHint: true, because the message leaves your organization.
• Sensitive write - A Write that can archive a record in a way MCP cannot undo, or that sends email and spends credits. Your AI client should ask for your approval every time it calls one of these tools.
  • mutate_opportunity_build and mutate_project_build can archive. MCP cannot restore an archived opportunity, and an archived Project rejects further changes. MCP annotations: readOnlyHint: false, destructiveHint: true; openWorldHint is false for mutate_opportunity_build and true for mutate_project_build, because import_from_provider reads your connected Linear or Jira workspace.
  • mutate_widgets can archive a widget. Nothing in Deck can restore an archived widget, and it stops accepting feedback. MCP annotations: readOnlyHint: false, destructiveHint: true, openWorldHint: false.
  • mutate_segments can archive a segment and delete a segment rule. MCP cannot restore either. MCP annotations: readOnlyHint: false, destructiveHint: true, openWorldHint: false.
  • mutate_competitors sends email and spends credits. Deck emails the person who started research when it finishes or fails, and emails organization members when a check-in is ready. Research runs and check-ins use the organization's credits, and set_checkins schedules recurring check-ins. It does not archive or delete anything, but set_checkins can turn scheduled check-ins off and replaces the cadence. Research reads public reviews on the web. Its MCP annotations are readOnlyHint: false, destructiveHint: true, openWorldHint: true.

openWorldHint: true tells your AI client that a tool reaches outside your Deck workspace. Five Deck tools have it: mutate_competitors, whose research reads public reviews on the web, submit_feedback, which sends your message to the Deck team, list_projects, whose importable_from mode reads your connected Linear or Jira workspace, and mutate_initiative_build and mutate_project_build, whose import actions read Linear or Jira. list_projects stays a Read tool (readOnlyHint: true): it changes nothing. The imports create records in Deck only; nothing changes in Linear or Jira. Every other tool works only with your Deck data.

All tools except get_user_context, select_organization, and submit_feedback need an organization with MCP access on and your role allowed (see Step 1). Write tools are available to every role that has MCP access, except set_checkins, which is admin-only.

Deck uses three OAuth scopes: profile, email, and offline_access. offline_access lets your AI client refresh its token without asking you to sign in again. 23 of the 31 tools only read data and are marked readOnlyHint: true, so if your assistant lets you limit a connector to reading data, those tools keep working and the eight write tools are left out. Deck has no separate read-only OAuth scope, so the limit comes from your assistant: without it, a connection can call every tool your role allows, and you can deny a write tool when the assistant asks for approval. An organization admin can also limit which roles can use MCP in Settings → MCP.

Every tool except get_user_context and submit_feedback takes an optional org_id. If you belong to one organization, the assistant can leave it out. If you belong to more than one, the assistant gets the ID from select_organization. The Key inputs column lists the other main parameters.

Outputs: Each tool returns JSON as text. Most read tools include deck_url links into the Deck web app and a _guidance object that suggests next calls. mutate_competitors returns request_id, action, result, deck_url, and _guidance. Build write tools, mutate_widgets, and mutate_segments return the envelope described in Write responses and retries. submit_feedback returns success, feedback_id, submission_id, synthesis_status, request_id, and _guidance, and no deck_url, because the feedback is in Deck's workspace. show_deck_view returns the view's facts as JSON text and in structuredContent; the view itself goes only to the client. create_from_insights returns saved: false with Deck's review, or, after you click Create, the created item with its deck_url.

See Errors and limits for what each tool returns when it cannot run.

Write responses and retries

The Build write tools (mutate_initiative_build, mutate_opportunity_build, mutate_project_build) return one of two shapes:

• Success: {"success": true, "data": {"action", "result", "request_id", "idempotency", "follow_up"}}. idempotency is {"key", "replayed"} ({"key"} only for imports), and follow_up suggests next tool calls.
• Failure: {"error": {"code", "message", "request_id", "details"}}. This comes back as a normal tool result without isError, so check for a top-level error key. Input validation failures, organization access errors, and Deck service outages are the exception: they return isError: true (see Other tool errors).

Deck builds an idempotency key from the tool, the action, and the input. If an identical Build write is sent again within 24 hours of a successful one, Deck does not run it again. It returns the stored result with idempotency.replayed: true. Deck stores only successful writes, so retrying a failed write runs it again. A retry sent while the first call is still running can return CONFLICT.

This applies to any identical write, not only retries. Setting a status back to a value you set through MCP earlier in that 24-hour window, assigning insights you unassigned, or generating a Project's Evidence story again all return the earlier result and change nothing. For example, if you set an initiative to building, then archived, then building again within 24 hours, the last call is replayed and the initiative stays archived. When idempotency.replayed is true and you meant to make the change, make it in the Deck web app.

Imports (import_from_provider, import_from_linear) follow the same rule: an import retried with the same payload within 24 hours replays the first result and creates nothing new. The import result does not report replayed. Deck stores only a completed import, so a retry after ALREADY_LINKED, PROVIDER_NOT_CONNECTED, or an error runs the import again.

start_research and add_competitor are not deduplicated: each accepted call starts a new research run and spends credits. While a run is in progress, both return CONFLICT, so a retry cannot start a second run at the same time. Identical promote_to_opportunity, assign_competitor_insights, and set_checkins calls in the same organization within 24 hours return the first result instead of running again. For example, if you turn check-ins on, then off, then on again with the same cadence within 24 hours, they stay off. These replays do not set replayed: true, so if a repeated change does not take effect, make it in Competitors settings.

mutate_widgets returns the same two shapes as the Build write tools, but idempotency has only key, with no replayed. Every update runs, so renaming a widget back to an earlier name, or linking a Project again after you unlinked it, takes effect. create and archive use the 24-hour rule: an identical call in the same organization returns the first result and changes nothing, and the response does not say so. For example, two create calls with the same name and Project within 24 hours return the first widget.

mutate_segments returns the same two shapes as the Build write tools, with idempotency.key and idempotency.replayed. Every update, update_rule, set_feedback_segments, and set_enabled runs, so setting a value back takes effect. create, archive, create_rule, delete_rule, and confirm_insight_segment use the 24-hour rule: an identical call in the same organization returns the first result with idempotency.replayed: true.

submit_feedback is not deduplicated. Each successful call stores one message, so do not send the same feedback again after a success.

Setup

Prerequisites

• A Deck account in a Deck organization with feedback data
• MCP access on for your organization and your role. New organizations have it on for admins and members. Organizations created before MCP was on by default keep their saved setting, which may be off (see Step 1)
• Organization admin access only if you need to change MCP settings
• MCP works on every Deck plan. explore_nps and explore_subthemes need the Starter plan or higher, and Competitors research and Project Evidence stories spend credits (see Errors and limits)
• Deck stores your organization's data in the hosting region chosen when the workspace was created (North America, Europe, or APAC). MCP tools read and write that same regional data
• One of the following AI assistants:
  • Claude Desktop (macOS or Windows)
  • Claude Code (CLI)
  • ChatGPT Plus, Pro, Business, Enterprise, or Education (with Developer Mode)
  • Cursor
  • Visual Studio Code
  • Windsurf
  • Zed
  • Codex (OpenAI)
  • Gemini CLI
  • Grok Build
  • Lovable
  • Muse by Meta
  • v0 by Vercel

Step 1: Enable MCP Access for Your Organization

MCP access is on by default for new organizations, for both admins and members. Organizations created before MCP was on by default keep their saved setting, which may be off.

To check or change the setting, an organization admin can:

1. Navigate to Settings → MCP in your Deck organization
2. In Access Control, turn Enable MCP Access on or off
3. Under Allowed Roles, select which roles can connect via MCP (at least one):
   • Admins - Organization administrators
   • Members - Regular organization members
4. Click Save Changes

If MCP is off or your role is not allowed, you can still sign in from your AI assistant, but Deck tools return AUTH_MCP_DISABLED or AUTH_ROLE_NOT_ALLOWED until an admin changes the setting.

Step 2: Configure Your AI Assistant

Choose the setup instructions for your preferred AI assistant below.

Claude Desktop

Add the following to your MCP configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "deck": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "https://mcp.getdeck.io/mcp"]
    }
  }
}

After saving the configuration:

1. Restart Claude Desktop completely
2. Claude will automatically detect the OAuth configuration from Deck's MCP server
3. Follow the Clerk OAuth flow to sign in to your Deck account
4. Grant access to the MCP integration
5. If you belong to one Deck organization, Deck uses it automatically. If you belong to more than one, ask Claude to run select_organization and choose one

Verify Connection: Look for the MCP server indicator (hammer icon) in the bottom-right corner of the input box. Click it to view available Deck tools.

Claude Code

Claude Code supports MCP servers via CLI commands. Use the following to connect to Deck:

Add the Deck MCP Server

# Add Deck MCP server (stored locally by default)
claude mcp add --transport http deck https://mcp.getdeck.io/mcp

Authenticate

Once added, authenticate within Claude Code:

# Start Claude Code
claude

# Open MCP management
> /mcp

# Follow the browser prompts to login with your Deck account

Installation Scopes

You can configure the scope of your MCP installation:

# Local scope (default) - private to you, stored in ~/.claude.json
claude mcp add --transport http deck https://mcp.getdeck.io/mcp

# Project scope - shared with team via .mcp.json file
claude mcp add --transport http deck --scope project https://mcp.getdeck.io/mcp

# User scope - cross-project, personal configuration
claude mcp add --transport http deck --scope user https://mcp.getdeck.io/mcp

Management Commands

# List all configured MCP servers
claude mcp list

# Get details for Deck server
claude mcp get deck

# Remove the Deck server
claude mcp remove deck

# Check server status (within Claude Code)
> /mcp

ChatGPT

ChatGPT supports MCP servers through the Connectors feature in Developer Mode.

Prerequisites

• ChatGPT Plus, Pro, Business, Enterprise, or Education subscription
• Developer Mode enabled

Enable Developer Mode

1. Open ChatGPT settings
2. Navigate to Apps & Connectors → Advanced settings
3. Enable Developer mode

Note: For Business/Enterprise workspaces, an admin must first enable Developer Mode in Workspace Settings → Permissions & Roles.

Add Deck Connector

1. Go to Settings → Apps & Connectors
2. Click Create under Connectors
3. Enter the following details:
   • Name: Deck Customer Feedback
   • Description: Access customer insights, themes, and feedback from Deck
   • MCP Server URL: https://mcp.getdeck.io/mcp
   • Authentication mode: OAuth
4. Select "I trust this application" to confirm
5. Click Create
6. Complete the Clerk OAuth login flow when prompted

How ChatGPT Connects

ChatGPT uses OAuth 2.1 with PKCE (Proof Key for Code Exchange) and Dynamic Client Registration:

1. ChatGPT queries Deck's OAuth discovery endpoint
2. Registers dynamically as an OAuth client
3. Initiates Authorization Code + PKCE flow
4. You authenticate with your Deck credentials
5. Access tokens are attached to all subsequent MCP requests

Deck view in ChatGPT

When an answer is best shown as a table, chart, or list of quotes, ChatGPT can open the Deck view (the show_deck_view tool) right in the conversation. Try "What are the biggest customer pain points?", "Show my top themes and NPS", or "Show the onboarding theme with customer clips".

• Inline view: a compact summary of the first few sections, with two actions: Expand opens the full view, and Open in Deck opens the same page in the Deck web app.
• Full view: every section. Click a theme, subtheme, insight, opportunity, or initiative to drill into it, and use Back to return. Other links open Deck in your browser.
• Customer pain points: a one-sentence verdict, your pain points ranked as groups, and three proof numbers: Negative insights, Customers affected, and Covered by an opportunity. Customers affected counts each customer once, and its note says how many of the insights have a known customer. A pain point is an insight with negative sentiment. The answer covers the last 90 days by default, dated by when the customer said it, and you can ask for the last 30, 180, or 365 days instead. Tap a group to open it in the full view.
• Pain point detail: an opened group shows Insights per week, By segment (when your organization uses segments), By category, Related in Deck, and What customers said. Use the Pain points breadcrumb to go back to the answer.
• Interview clips: quotes from recorded calls can play their video clip in place. Clip links expire after an hour; when you reopen an older conversation, the view loads without clips and then refreshes once to bring them back.
• Deck home: the Deck entry in ChatGPT's sidebar opens your home view: key metrics, top themes, top opportunities, and active initiatives. The metrics include Feedback analyzed (pieces of feedback with insights) and Added in the last 7 days (insights, by the date they were imported). NPS metrics and the NPS breakdown show only on the Starter plan or higher.
• Multiple organizations: if your account belongs to more than one Deck organization, the view asks you to choose one first.
• Partial results: if one section fails to load (for example, a feature your plan does not include), the rest of the view still appears and that section says why.

Keep asking in the chat

On ChatGPT on the web, an answer opens in the Deck panel on the right of the conversation. When you type a follow-up that changes what you see, such as asking for one segment, all segments again, or another view like your opportunities, ChatGPT opens a new Deck view in that panel, and your earlier views stay in the conversation. If you close the panel, the view stays in the conversation as a smaller card that you can expand again. Inside the view, you can click a row, a breadcrumb, All segments, or Look at the last 12 months to move around without opening a new view. Creating from the view opens Deck's review first, and nothing is saved until you confirm it there. The ChatGPT desktop and mobile apps are not verified yet.

Labels in a pain-point answer

• Grouped by theme: Deck grouped your pain points by theme because subthemes aren't available to your organization yet, for example on the Free plan or before Deck's first weekly grouping. Otherwise each group is a subtheme.
• AI wording: ChatGPT gave the group a clearer name. Deck's own name for the group shows next to it, and every number still comes from Deck.
• Covered, Related opportunity, and Not covered: an opportunity in your backlog already holds some of the group's insights (Covered), an opportunity about the same theme exists but holds none of them (Related opportunity), or neither (Not covered).
• Newer insights aren't grouped yet: the note under the answer, such as "4 newer insights aren't grouped yet", counts recent negative insights that Deck hasn't put in a group. They join a group after the weekly run.

Creating from a pain point

In the full view, a pain point's detail ends with buttons to turn it into work:

• Create opportunity, Create project, and Create initiative open a review step, and nothing is created until you confirm it there. When an opportunity already covers the group, Open the opportunity takes the place of Create opportunity.
• The title starts as Deck's name for the pain point. If ChatGPT gave the group clearer wording, the title starts with that wording instead, marked AI wording from ChatGPT., and Use Deck's name switches back. An opportunity's problem statement starts as Deck's summary of the pain point. You can choose an initiative for a Project, and give an initiative a goal.
• The pain point's insights are attached as evidence (the 100 most recent when there are more). The review step notes Uses no credits: creating spends no credits and starts no AI generation.
• When a related opportunity exists, Create opportunity first lets you choose between Add evidence to that opportunity, which keeps one opportunity for the problem, and Create a new opportunity.
• Depending on your ChatGPT approval settings, ChatGPT may ask you to allow the create. While the view waits it shows Waiting for ChatGPT. If ChatGPT asks, nothing is saved until you allow it.
• You can also ask ChatGPT in the conversation to create from a pain point, for example "Create an opportunity from the top pain point". ChatGPT opens Deck's review of that pain point in the Deck view, filled in, and nothing is saved until you click Create there.
• Opportunities you create stay in your backlog through weekly rebuilds. The Deck view marks what you created with Created by you.
• Draft a PRD in chat sends the pain point to ChatGPT as your next message, so ChatGPT can draft a PRD from it. The button shows only where ChatGPT supports sending a message from the view.

The view only shows data from your Deck organization and never deletes or archives anything. ChatGPT still writes the answer in chat; the view only shows what Deck loaded. If your admin has turned on PII redaction, the view shows masked customer details.

Limitations

• OAuth only - API key authentication is not supported
• No machine-to-machine grants - Client credentials and service accounts are not supported
• HTTPS required - ChatGPT only connects to secure endpoints

Cursor

Cursor has built-in MCP support. You can add Deck using either the quick install or manual configuration.

Quick Install

Click here to install Deck in Cursor

This will automatically configure Cursor with the Deck MCP server.

Manual Configuration

1. Open Cursor Settings (Cmd/Ctrl + ,)
2. Navigate to Features → MCP
3. Click Add new MCP server
4. Enter the following:
   • Name: Deck
   • URL: https://mcp.getdeck.io/mcp
5. Save and authenticate when prompted

Alternatively, you can edit your Cursor MCP configuration file directly:

macOS: ~/.cursor/mcp.json

Windows: %APPDATA%\Cursor\mcp.json

{
  "mcpServers": {
    "deck": {
      "url": "https://mcp.getdeck.io/mcp"
    }
  }
}

Visual Studio Code

VS Code supports MCP servers through the built-in MCP extension.

Quick Install

Install Deck in VS Code

This adds Deck as a remote HTTP server. Sign in when VS Code asks.

Setup

1. Open the Command Palette (Ctrl/Cmd + Shift + P)
2. Search for "MCP: Add Server"
3. Choose HTTP
4. Enter https://mcp.getdeck.io/mcp
5. When prompted for a name, enter Deck
6. Follow the OAuth prompts to authenticate with your Deck account

If your VS Code build only offers a local command, use:

npx -y mcp-remote@latest https://mcp.getdeck.io/mcp

Verify Connection

Open the Command Palette and run "MCP: List Servers" to verify Deck is connected.

Windsurf

Windsurf Cascade connects to remote HTTP MCP servers with serverUrl.

Setup

1. Open Windsurf Settings
2. Navigate to Cascade → MCP servers
3. Click Add custom server, or edit ~/.codeium/windsurf/mcp_config.json
4. Add the following configuration:

{
  "mcpServers": {
    "deck": {
      "serverUrl": "https://mcp.getdeck.io/mcp"
    }
  }
}

5. Save the configuration
6. Follow the OAuth prompts to authenticate with your Deck account

Zed

Zed supports MCP through context servers in its settings.

Setup

1. Open Zed Settings (Cmd + ,)
2. Add the Deck context server to your configuration:

{
  "context_servers": {
    "deck": {
      "command": {
        "path": "npx",
        "args": ["-y", "mcp-remote@latest", "https://mcp.getdeck.io/mcp"]
      }
    }
  }
}

3. Save the settings file
4. Follow the OAuth prompts to authenticate with your Deck account

Codex (OpenAI)

OpenAI's Codex CLI connects to Deck as a remote HTTP MCP server.

Add Deck Server

codex mcp add deck --url https://mcp.getdeck.io/mcp

Authenticate

Finish the Deck sign-in in the browser. If it does not open, run:

codex mcp login deck

v0 by Vercel

v0 connects Deck as a custom MCP server with OAuth.

Setup

1. In a v0 chat, open the Connect tab, or use the project menu → Settings → Integrations
2. Add an MCP server named Deck
3. Enter https://mcp.getdeck.io/mcp and choose OAuth
4. Add the server and sign in to Deck

Once connected, v0 can use Deck customer feedback while generating UI and code.

Gemini CLI

Gemini CLI stores Deck in your user settings and signs in from the session:

gemini mcp add -s user --transport http deck https://mcp.getdeck.io/mcp

Start Gemini CLI and run /mcp auth deck.

Grok Build

Grok Build adds Deck over HTTP. The first Deck tool opens browser sign-in:

grok mcp add --transport http deck https://mcp.getdeck.io/mcp

You can also run /mcps, select deck, and press i.

Claude Code, Codex, and Grok Build can install the Deck plugin instead. The plugin bundles this MCP server.

Lovable

1. Open Connectors and choose the Custom MCP card
2. Paste https://mcp.getdeck.io/mcp
3. Leave authentication on OAuth and choose Add & authorize
4. Sign in to Deck

Muse by Meta

Deck's hosted MCP server uses OAuth with PKCE, so you do not need an API key to connect Muse.

Server URL: https://mcp.getdeck.io/mcp

Connect Deck to Muse

1. Meta's Muse connector guidelines say approved connectors are discoverable by the Muse agent and in Settings → Connectors. If Deck is approved, find it there or ask Muse to connect Deck. If Deck is not listed, your Muse app may let you add a custom MCP connector. Meta has not published steps for custom connectors, so that option may not be available and the screens may differ. If it is available, use the server URL https://mcp.getdeck.io/mcp
2. When the Deck sign-in page opens, sign in to your Deck account and approve access
3. If you belong to more than one Deck organization, Deck tells the assistant to call select_organization to list your organizations. The assistant should then pass the chosen organization's org_id on each Deck tool call

Deck never asks you to paste a password, access token, or API key into the chat. Sign in only on the Deck sign-in page.

Approvals in Muse

If Muse asks for your approval before it runs a tool, use the class in the tool reference to decide. Every Deck tool is a Read, Write, or Sensitive write. Write tools carry the MCP annotation readOnlyHint: false. There are five Sensitive write tools. mutate_opportunity_build, mutate_project_build, mutate_widgets, and mutate_segments can archive or delete records in a way MCP cannot undo, and also carry destructiveHint: true. mutate_competitors sends email and spends credits, and carries destructiveHint: true because set_checkins can turn scheduled check-ins off, and openWorldHint: true because research reads public reviews on the web. mutate_initiative_build is a Write, but it also carries destructiveHint: true because it can overwrite an initiative's content, so Muse may ask before it runs too. submit_feedback is a Write that carries openWorldHint: true, because it sends your message to the Deck team. Approve each of those calls only when you want that exact change.

Generic MCP Clients

For any MCP-compatible tool not listed above, use these connection details:

Streamable HTTP

URL: https://mcp.getdeck.io/mcp

Deck supports only the Streamable HTTP transport, at this URL. There is no SSE endpoint, so if your client asks you to choose, pick HTTP or Streamable HTTP, not SSE.

Local command (via mcp-remote)

For a client that can only start a local command, mcp-remote connects it to the same URL:

Command: npx

Arguments: ["-y", "mcp-remote@latest", "https://mcp.getdeck.io/mcp"]

Refer to your client's documentation for specific configuration instructions.

Usage Examples

Once connected, you can ask your AI assistant questions about your customer feedback. Here are example prompts organized by use case:

Discovery & Overview

• "Give me a summary of all customer feedback themes"
• "What are the top 5 most mentioned issues this quarter?"
• "How many insights do we have in each category?"
• "How many credits do we have left?"
• "Which features are on for this workspace?"

Sentiment Analysis

• "Show me all negative sentiment insights from last month"
• "Compare positive vs negative feedback trends"
• "Which themes have the most negative sentiment?"
• "What's the overall sentiment distribution across our feedback?"

Deep Dive Research

• "Search for insights related to pricing concerns"
• "What did customers say about the onboarding experience?"
• "Show me the full transcript from the most recent user interview"
• "Find all feedback mentioning competitor products"
• "Summarize our competitor landscape"
• "List competitor insights about onboarding"
• "Add Rival as a competitor and start research"
• "Promote that competitor onboarding teaser into Opportunity Backlog"
• "Assign these competitor insights onto the existing onboarding opportunity"

Cross-Reference Analysis

• "Which feedback sources mention both 'pricing' and 'value'?"
• "List all insights in the 'Feature Requests' category"
• "Show me themes that appear across multiple feedback types"

NPS & Satisfaction

• "What is our current NPS score?"
• "Show me what our detractors are saying"
• "How has our NPS trended over the last 6 months?"
• "What are the top recommendations to improve our NPS?"
• "What percentage of our responses are promoters vs detractors?"

Product Planning

• "What features are customers requesting most?"
• "Summarize pain points mentioned in user interviews this month"
• "What do customers love most about our product?"
• "Identify the top 3 issues we should prioritize fixing"

Segment Analysis

If your organization uses customer segments, the AI can break down feedback by segment:

• "Show me feedback from enterprise customers only"
• "What are the top themes for our SMB segment?"
• "Compare sentiment between our free and paid user segments"
• "Which subthemes are most common in the mobile segment?"

Feedback Widgets

• "List our feedback widgets and how much feedback each one got"
• "Create a feedback widget for the onboarding Project and install the SDK in this app"
• "Archive the old beta widget"
• "Tell Deck this MCP answer looks wrong"

The last prompt sends feedback about Deck itself (submit_feedback). It does not store a note in your workspace.

Visual Views (ChatGPT)

In clients that support MCP Apps, such as ChatGPT, these prompts open the Deck view:

• "Show my Deck home"
• "Show our top themes and NPS"
• "Compare the pricing and onboarding themes"
• "Show the latest insights about onboarding with their clips"
• "Show the opportunity backlog and our active initiatives"

The AI assistant will use the MCP tools to query your Deck data, suggest next steps, and perform scoped Build actions only when you ask it to.

Deck Plugin for Claude Code, Codex, and Grok

If you use Claude Code, Codex, or Grok Build, you can install Deck's plugin instead of configuring the MCP server manually. The plugin bundles the hosted Deck MCP server configuration and adds Deck-specific skills for the improvement loop: discovery, ranking, initiative briefs, Project briefs, and NPS.

Install the Deck Plugin

Managing Access & Connections

Access Control (Admin Only)

Organization admins can control MCP access from the Access Control card in Settings → MCP:

• Enable MCP Access: Turn MCP access on or off for the entire organization. It is on by default for new organizations; older organizations keep their saved setting
• Allowed Roles: Choose which roles can connect (at least one must stay selected):
  • Admins only for restricted access
  • Admins and Members for broader team access (the default)
• Click Save Changes. Changes apply on the next tool call - users whose role is not allowed get AUTH_ROLE_NOT_ALLOWED

Connection Analytics

Admins can monitor MCP usage:

• View the Connected Users list to see who has connected via MCP
• Each entry shows:
  • User name, avatar, and email
  • Connection date and last used time
• Use this to see who is connecting. The list has no disconnect or revoke button

Disabling Access

If MCP is disabled:

• Users can still sign in from their AI assistant, but Deck tools that use organization data return AUTH_MCP_DISABLED, which tells the user to ask an admin to turn MCP back on
• Existing connections get that error on their next tool call
• A connected assistant can still read the user's own profile (get_user_context), and select_organization lists the organization as unavailable with the reason mcp_disabled
• Re-enabling MCP restores access for allowed roles on the next tool call, without reconnecting

Security

Deck's MCP server implements robust security measures:

Authentication

• OAuth 2.0 / 2.1: All connections use Clerk OAuth for secure authentication
• PKCE Support: Proof Key for Code Exchange prevents authorization code interception attacks
• Dynamic Client Registration: Supports RFC 7591 for clients like ChatGPT that register dynamically
• Token Management: OAuth tokens are managed securely by Clerk with automatic refresh
• Scopes: profile, email, and offline_access. No separate read-only scope; the 23 read tools are marked readOnlyHint: true so an assistant can limit a connection to them (see Tool reference)

Data Protection

• Read-first design: Most MCP tools are read-only and return links back to Deck for review
• Bounded mutations: Build mutation tools are limited to specific Project, initiative, and opportunity actions. Competitor writes are limited to research, add-competitor, promote, assign competitor insights, and (admins only) set_checkins. create_from_insights only adds records and evidence, and saves only after you click Create in Deck's review. Widget writes are limited to create, rename, link or unlink a Project, and archive. No tool creates, shows, or revokes a full publishable key.
• Organization Scoping: Connections are automatically scoped to your organization
• Feedback to Deck: submit_feedback is the only tool that writes outside your organization. It sends the message and any details the assistant adds, with your user ID, email address, name, organization ID, and AI client, to the Deck team
• Role-Based Access: Admins control which roles can connect via MCP
• PII Redaction: When an admin turns on PII redaction, Deck masks respondent names, email addresses, and phone numbers (including inside quotes, transcripts, and summaries) before any MCP tool, resource, or the Deck view returns data to your AI assistant. Speaker labels and video clips are not changed

Access Control

• To disconnect an AI client, remove the Deck connector in that client
• An organization admin can turn MCP off in Settings → MCP. Deck tools then return AUTH_MCP_DISABLED on the next call
• Expired or invalid tokens get HTTP 401. The AI client refreshes its token, or asks you to sign in to Deck again if it cannot
• Admins can see who has connected in the Connected Users list in Settings → MCP

Errors and limits

Sign-in errors (HTTP 401)

Deck returns HTTP 401 only when the access token is missing, invalid, or expired, or when Deck briefly cannot load your organization memberships. For an expired token, your AI client refreshes it (Deck grants offline_access for this), or asks you to sign in to Deck again if it cannot. A 401 caused by a failed membership lookup clears on retry. A 401 does not mean MCP is off for your organization; that case returns a tool error instead.

Malformed requests (HTTP 400)

A signed-in POST to https://mcp.getdeck.io/mcp whose body is not valid JSON gets HTTP 400 with the JSON-RPC error {"code": -32700, "message": "Parse error"}. Sign-in is checked first, so a request without a valid token gets the HTTP 401 sign-in challenge instead.

Organization access errors

When sign-in works but Deck cannot use the organization, the tool result has isError: true and a JSON body such as {"error": {"code": "AUTH_MCP_DISABLED", "message": "..."}}. The message explains the fix.

Other tool errors

• Input that does not match the tool's schema, such as a malformed ID, an unknown action on any write tool, or a limit out of range, returns isError: true with text that starts MCP error -32602: Input validation error: and names the invalid fields. Fix the input and call again.
• The six mutate_* write tools list a required action and every field any action uses. Those fields are optional in the listing and labelled Used by: <actions>. After the schema check, the tool checks the fields the chosen action needs. If one is missing or does not fit that action, all six return the same isError: true text that starts MCP error -32602: Input validation error:. For example, a mutate_widgets update with neither name nor project_id returns it. create_from_insights checks its whole input before it runs and returns the same text when the input does not fit.
• A few rules that depend on more than one field are checked later. mutate_project_build upsert_section without content, or with content that is not an array of editor block nodes, returns VALIDATION_ERROR in the Build error envelope. link_external_artifact accepts a Jira or Linear URL alone: Deck reads the provider and the key from external_url. A URL on another host, a provider that does not match the URL, or a URL with no key and no external_id (for example a Linear issue URL) returns VALIDATION_ERROR, and nothing is written. import_from_provider with provider: linear and artifact_type: epic, or provider: jira and artifact_type: project, returns VALIDATION_ERROR in the Build error envelope before Deck calls Linear or Jira. mutate_competitors promote_to_opportunity without source_id (for a subtheme or teaser) or insight_ids (for source_type: insights) returns MUTATE_COMPETITORS_FAILED with statusCode: 400.
• Write tools always record the change as the signed-in user. Clients cannot set the acting user.
• create_from_insights returns isError: true with a fixed message when Deck refuses the create, for example when an ID does not exist in this organization. Nothing is saved.
• VALIDATION_ERROR from a Build write tool - The input passed those checks, but Deck rejected it. For example, assign_evidence with no insight, theme, or subtheme IDs, or a payload Deck's API refuses. It comes back in the Build error envelope described below.
• *_NOT_FOUND (for example INSIGHT_NOT_FOUND) and NOT_FOUND - The ID does not exist in this organization, or the record may have been archived.
• SEGMENT_NOT_FOUND - explore_segments got a segment_id that is not a segment of this organization. Call explore_segments without segment_id to list segments.
• INVALID_SEGMENT_RULE - Deck refused the preview_rule of explore_segments. The message is Deck's sentence, for example that a CRM field rule needs a field name.
• EXPLORE_SEGMENTS_FAILED - Deck rejected the explore_segments request for another reason. The message says why.
• CONFLICT - The write conflicts with the current state. For example, start_research and add_competitor return it while Competitors research is already running.
• PROVIDER_NOT_CONNECTED - import_from_provider, import_from_linear, or link_external_artifact with fetch_from_provider needs Linear or Jira, and that integration is not connected for your organization. Connect it in Deck under Settings > Integrations, then retry. Nothing is written.
• PROVIDER_ARTIFACT_NOT_FOUND - link_external_artifact with fetch_from_provider names a Jira or Linear item that your connected workspace does not have. For a Linear URL alone, pass the Linear project ID as external_id. Nothing is written.
• ALREADY_LINKED - an import names a Jira or Linear item that is already linked in Deck, or mutate_project_build link_external_artifact names a Jira or Linear item that is already linked to another Deck Project. The message is the sentence the web app shows, for example "This Jira item is already linked to another Deck project". details.details.linked_project_id is the Project that has the link. Nothing is written. Unlink the item from that Project first, or link a different item.
• ROLE_NOT_ALLOWED - A member called mutate_competitors with set_checkins, which is admin-only. The error includes settings_url, a link to Settings → Competitors, so you can ask an admin to change check-ins there.
• PLAN_UPGRADE_REQUIRED (statusCode: 402) - The Free plan does not allow the change. start_research and add_competitor return it after the organization used its one competitor report. set_checkins with enabled: true returns it on the Free plan. The message tells the user to upgrade the plan.
• CREDIT_LIMIT_EXCEEDED (statusCode: 402) - start_research or add_competitor was refused because the organization does not have enough credits for the research. Research does not start. The error has recovery_suggestions and a _guidance.suggested_next that points to explore_workspace with view=credits. It does not show the credit balance.
• *_FAILED (for example EXPLORE_INSIGHTS_FAILED or MUTATE_COMPETITORS_FAILED) - The request failed; the message and statusCode say why.
• EXPLORE_INTEGRATIONS_FAILED - Deck refused the explore_integrations request, for example an unknown integration_type. The message is Deck's reason and statusCode is the HTTP status.
• SLACK_NOT_CONNECTED - explore_integrations with view: slack_channels found no Slack connection. deck_url opens the Slack settings, and suggested_next points to explore_integrations with integration_type: SLACK.
• Build write tools (mutate_initiative_build, mutate_opportunity_build, mutate_project_build), mutate_widgets, and mutate_segments return errors from Deck as a normal tool result without isError. The text is {"error": {"code", "message", "request_id", "details"}} with codes VALIDATION_ERROR, AUTH_ERROR, NOT_FOUND, CONFLICT, ALREADY_LINKED (mutate_project_build links and both import actions), PROVIDER_NOT_CONNECTED (import actions and link_external_artifact with fetch_from_provider), PROVIDER_ARTIFACT_NOT_FOUND (link_external_artifact with fetch_from_provider), RATE_LIMIT, or API_ERROR. Check for a top-level error key. For example, mutate_widgets update on an archived widget returns CONFLICT, and mutate_segments returns VALIDATION_ERROR with Deck's sentence for a duplicate segment name or a circular segment rule. mutate_segments also returns VALIDATION_ERROR before it calls Deck when the payload does not pass its checks, for example rule_type: "tag".
• INVALID_CURSOR - list_widgets got a cursor that it did not make. Call it again without cursor.
• submit_feedback returns isError: true with VALIDATION_ERROR (context is larger than 8000 characters as JSON), FEEDBACK_NOT_CONFIGURED (feedback to Deck is not set up on this server), AUTH_REQUIRED (the call has no signed-in Deck user; sign in to Deck again), RATE_LIMITED (too much feedback in the last minute; wait one minute), or FEEDBACK_UNAVAILABLE (Deck could not record it now; try again later). Each error has a request_id. After a timeout, FEEDBACK_UNAVAILABLE can come back although Deck stored the message, so a retry can store it twice.
• If a Deck service is down (HTTP 5xx), the tool returns isError: true with text such as MCP error -32020: explore_insights failed: .... Build write tools and the widget tools do this too. This is a tool result, not a JSON-RPC error. Try again later. For the Build write tools, mutate_widgets, mutate_segments, and mutate_competitors, the text ends with (request_id: ...). The write can have run, so check the record before you try again. To report the problem, send that request_id with submit_feedback.

Plan and feature limits

• explore_nps and explore_subthemes need the Starter plan or higher. On the Free plan they return a normal result with feature_unavailable: true, required_tier: "Starter+", and suggested alternatives, not an error. See Billing & Credits.
• explore_competitors and mutate_competitors return feature_unavailable: true when Competitors is off for the workspace. An admin can turn it on in Settings → Competitors. The result includes settings_url, a link to that page.
• Competitor caps by plan (for example, 5 tracked competitors on Starter, and 1 competitor report on Free) apply to MCP the same way as in the app. See Billing & Credits.
• On the Free plan, start_research and add_competitor research only the first 2 competitors in the request, at 10 reviews per source. When that changes the request, the research result includes depth_reduced: true, reviews_per_source: 10, and a message that says the depth was reduced because the organization is on the Free plan.

Rate limits and credits

Deck does not publish a fixed request quota for the MCP server. Each tool limits page and batch sizes in its input schema, for example up to 20 resources for get_platform_links and 1–25 competitors for start_research.

If a Deck service responds with HTTP 429, Build write tools, mutate_widgets, and mutate_segments return RATE_LIMIT, submit_feedback returns RATE_LIMITED, other tools return their *_FAILED error with statusCode: 429, and get_overview returns isError: true with text that starts MCP error -32021: when every request behind it is rate limited. Wait a moment, then try again.

Competitors research, periodic check-ins, and generate_evidence_story spend credits. See Billing & Credits. To see the plan, the credits left and the items that wait for credits, ask the assistant to call explore_workspace with view=credits. When mutate_competitors returns a credit error, its _guidance.suggested_next points to that call. When the organization does not have enough credits and overage is off:

• start_research and add_competitor check credits before research starts. They return CREDIT_LIMIT_EXCEEDED (statusCode: 402), and no research job is created. During the competitor free window, research does not need credits. If the credits run out after the check, research stops and Deck emails the person who started it that the workspace is out of credits.
• Deck skips a due check-in, without email, and tries again later. A check-in that runs out of credits partway stops without email.
• generate_evidence_story does not run. It returns the Build error envelope with code CONFLICT, message Failed to execute project mutation, and "details": "CREDIT_LIMIT_EXCEEDED" inside details.

Long-running Competitors research

Before start_research or add_competitor, the assistant can call explore_competitors with view=settings. It shows the most credits one research run can use, whether research is free until a date (check-ins still use credits), whether a Free organization already used its one report, whether research is running, the check-in schedule and the plan's competitor cap.

start_research and add_competitor return as soon as the job starts. Research runs in the background and can take more than 5 minutes. To check progress, ask the assistant to call explore_competitors with the returned job_id. Deck also emails the person who started the research when it finishes or fails. While research is running, start_research and add_competitor return CONFLICT.

Troubleshooting

Connection Issues

Server not appearing in Claude Desktop:

1. Verify the MCP server URL is correct: https://mcp.getdeck.io/mcp
2. Check JSON syntax in your configuration file
3. Restart Claude Desktop completely (quit and reopen)
4. Check logs:
   • macOS: ~/Library/Logs/Claude/mcp*.log
   • Windows: %APPDATA%\Claude\logs

Claude Code connection issues:

1. Verify the server was added: claude mcp list
2. Try removing and re-adding: claude mcp remove deck then add again
3. Re-authenticate via /mcp command

ChatGPT connector issues:

1. Ensure Developer Mode is enabled in settings
2. Verify you have a ChatGPT Plus, Pro, Business, Enterprise, or Education plan
3. Check that the MCP Server URL is exactly: https://mcp.getdeck.io/mcp
4. Try removing and recreating the connector

Cursor connection issues:

1. Verify the server appears in Settings → Features → MCP
2. Check that the URL is exactly: https://mcp.getdeck.io/mcp
3. Try using the quick install link
4. Restart Cursor and re-authenticate

VS Code connection issues:

1. Ensure you have an MCP extension installed and enabled
2. Run "MCP: List Servers" from Command Palette to verify Deck is configured
3. If you added Deck with the mcp-remote command, check that npx is available in your system PATH
4. Try removing and re-adding the server

Windsurf connection issues:

1. Verify the configuration in Cascade → MCP servers
2. Ensure the JSON syntax is correct
3. Restart Windsurf after making configuration changes
4. If you connect through the mcp-remote command instead of serverUrl, check that npx is available in your system PATH

Zed connection issues:

1. Verify the context_servers configuration in Zed settings
2. Ensure the JSON syntax is valid
3. Check that npx is available in your system PATH
4. Try restarting Zed

Codex connection issues:

1. Verify experimental rmcp is enabled in ~/.codex/config.toml
2. Run codex mcp list to verify Deck is configured
3. Try removing and re-adding: codex mcp remove deck then add again
4. Ensure you're running a recent version of Codex

Muse connection issues:

1. Check that the server URL is exactly: https://mcp.getdeck.io/mcp
2. Finish the Deck sign-in and approve access when prompted
3. If Muse keeps asking you to sign in, disconnect Deck and connect it again, if your Muse app lets you
4. If Deck tools return AUTH_MCP_DISABLED, AUTH_ROLE_NOT_ALLOWED, or AUTH_NO_ORG, see Authorization Errors below

Authorization Errors

Tools return AUTH_MCP_DISABLED, AUTH_ROLE_NOT_ALLOWED, or AUTH_NO_ORG:

Sign-in worked and the connection stays signed in, but Deck cannot use your organization yet. You do not need to reconnect.

• AUTH_MCP_DISABLED: ask an organization admin to turn on Enable MCP Access in Settings → MCP
• AUTH_ROLE_NOT_ALLOWED: ask an organization admin to add your role under Allowed Roles in Settings → MCP
• AUTH_NO_ORG: finish creating or joining a Deck organization in the Deck web app

Then ask the assistant to try again. See Errors and limits for every code.

ORG_AUTHORIZATION_UNAVAILABLE error:

• Deck could not verify your organization access. This is temporary; wait a moment and try again

OAuth flow not completing:

• Ensure you're signed in to your Deck account
• Try signing out of Deck and re-authorizing
• Clear browser cookies and try again

Asked to sign in again (HTTP 401):

• Your access token is missing, invalid, or expired, and your AI client could not refresh it. Sign in to Deck again from your AI client
• If you were signed in a moment ago, try the request again first. Deck also returns 401 when it briefly cannot load your organization memberships, and that clears on retry

"OAuth discovery failed" (ChatGPT):

• This may indicate a temporary server issue
• Wait a few minutes and try again
• Ensure your network allows connections to mcp.getdeck.io

Access Control Issues

If you suddenly lose access, your organization admin may have:

• Disabled MCP entirely (tools return AUTH_MCP_DISABLED)
• Changed the allowed roles and your role is no longer permitted (tools return AUTH_ROLE_NOT_ALLOWED)

Contact your organization admin to request access restoration.

Support

For additional help with the MCP integration, email support@getdeck.io or visit our documentation at docs.getdeck.io.

• Privacy Policy
• Terms of Service