Skip to content
Actual Voice
All documentation

Integrations · Insights and Question Builder

Connect with MCP

Explore your Actual Voice insights in Claude or another compatible AI assistant. The Model Context Protocol (MCP) lets your assistant read processed feedback from the workspaces you can access. You can also create and polish a Question in conversation, then check the preview and publish it yourself.

Remote MCP server URL

https://www.actualvoice.ai/mcp

Streamable HTTP · OAuth required · Scope: insights:read or questions:create, or both

Connect your assistant

Any registered Actual Voice account can connect. Add the server URL to a client that supports remote MCP and OAuth. Sign in, choose the requested permissions and select the organizations this connection may use. Creation requires membership in an active organization.

Compatible clients register automatically using OAuth metadata or dynamic client registration. Public clients use PKCE and do not need a client secret. Existing confidential clients remain supported.

Give your assistant the organization name and Question text. Optional settings can be added gradually. To add an organization or a permission later, reconnect and approve the new selection. Finish existing drafts first: reconnecting invalidates the old connection and its unpublished previews.

Try this prompt

Use Actual Voice to list my workspaces and Questions. Ask which Question I want to explore, then load its processed insights. Summarize the strongest patterns and practical next steps. Separate the reported results from your interpretation, and tell me when data is unavailable.

Create a Question

In my Downtown organization, create a Question asking “What would improve your next visit?” Turn contact collection off, add an optional first-visit or returning-visitor choice, and show me a preview before publishing.

Your assistant returns a private preview link. Sign in with the same Actual Voice account, review the organization and respondent steps, and click Publish Question. Then ask your assistant for the distribution link or QR code. Saying “yes” in the conversation does not publish.

Available tools

Your assistant uses these three tools in order. All are read-only.

get_access_context
Lists your current account and accessible workspaces. Takes no arguments.
list_questions
Lists Questions and their analysis status in one workspace. Requires workspace_id. Optional limit accepts 1–100 (default 50). Pass the returned next_cursor as cursor to read the next page, until it is null.
get_analysis_result
Loads the completed, all-time processed snapshot for a Question. Requires question_id. It does not accept date or demographic filters or trigger new analysis.

Question Builder tools

These tools require questions:create. They can save private drafts; publication requires your separate browser confirmation.

get_question_builder_context
Find authorized organizations, defaults, categories and demographic presets.
create_question_draft
Start a private draft in an explicit organization. Missing text can be filled in later.
update_question_draft
Polish the current revision. Edits invalidate the previous preview.
get_question_draft
Resume a draft or retrieve its publication receipt after confirmation.
prepare_question_review
Validate the configuration and check content safety, then return a private preview link.
discard_question_draft
Discard an unpublished draft. Published Questions are preserved.
get_question_distribution
Return the distribution link, optional campaign labels and a PNG or SVG QR code.
Download the Question Builder tool schemas

When available, results include Summary, response statistics, Sentiment, Engagement, Signal Map, Topics, Suggestions, and Demographic Insights. Check the snapshot timestamp before treating a result as current.

Data and privacy

  • Access follows your current Actual Voice workspace membership. The connector cannot grant access to another workspace.
  • A Question needs at least five eligible responses before processed insights are returned. Additional privacy checks can withhold individual sections.
  • Demographic labels, counts, and shares may be included. Segments with fewer than five responses have no Sentiment or Engagement scores. Custom or unmapped answers are grouped without exposing their original text.
  • Signal Map data may include numeric Engagement and sentiment pairs with no respondent identifiers, timestamps, demographics, text, or original response order.
  • Audio, transcripts, individual responses, contact details, and respondent identifiers are never returned.
  • The connector can prepare private Question drafts. It cannot publish without your browser confirmation, edit existing published Questions, run analysis or change organization membership.
  • Access also follows the organizations selected during OAuth. Removing membership or revoking the connection blocks further access. Unpublished drafts expire after seven days without an edit; previews expire after 30 minutes.
  • Authoring copy is sent for automated safety review before a preview is prepared. No respondent data is used. Private preview pages exclude product analytics and session replay. Keep personal information out of Question text, demographics and campaign labels.

Insights you request are shared with your chosen assistant. Its own data handling and retention terms apply to that conversation.

Read the Actual Voice Privacy Policy

Manage or revoke connected MCP apps

Troubleshooting

The server URL shows an authentication error
Opening /mcp directly without a token returns HTTP 401. Add the URL in your assistant's connector settings and complete OAuth sign-in.
OAuth setup fails
Use the exact server URL above. The client must support remote HTTP MCP, OAuth Authorization Code with PKCE S256, and a valid registered callback. Follow the authorization-server metadata; do not send your Actual Voice password or tokens in a conversation.
A preview is unavailable or safety review fails
Use the same account as the MCP connection and check that the organization is still authorized. Edits require a new preview. If the safety service is unavailable, your draft stays saved and publication stays blocked; retry later. Reconnecting requires a new draft.
A workspace or Question is missing
Check that you signed in with the intended account and still belong to the workspace. Missing or inaccessible Questions both return not_found_or_forbidden.
Insights are unavailable
Check the Question in Actual Voice. It may need more eligible responses, or its processed snapshot may be pending or failed. If artifact_unpublishable persists, contact the team; the snapshot did not pass the publication checks.
Requests are rate limited
Pause and retry later. Each account and client connection is limited to 30 tool calls per minute and 300 per hour.
The endpoint returns 404
Check the server URL. If it is correct, the MCP service may be disabled. Contact the Actual Voice team to confirm availability.

For developers

Use Streamable HTTP with OAuth Authorization Code and PKCE S256. Register your callback through dynamic registration or a Client ID Metadata Document.The resource is https://www.actualvoice.ai/mcp and the scope is insights:read and/or questions:create. Token requests support client_secret_basic and client_secret_post, plus none for public PKCE clients.

Workspace and Question IDs are UUIDs returned by the tools. Access and Question-list results use schema version 1.0; analysis results use 1.1. Successful calls include structured JSON in structuredContent. Tool failures set isError and return a JSON text block with code, message, and request_id.