Skip to content
Actual Voice
All documentation

Integrations · Read-only access

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.

Remote MCP server URL

https://www.actualvoice.ai/mcp

Streamable HTTP · OAuth required · Scope: insights:read

Connect your assistant

You need an Actual Voice account with access to a workspace, a compatible MCP client, and an OAuth client ID and secret registered by the Actual Voice team. Client registration is currently arranged with the team.

Request connection setup
  1. Open your assistant's custom MCP connector settings. Add a connector named Actual Voice using the server URL above.
  2. Require OAuth authentication and choose the option to use your own OAuth client. Enter the client ID and secret supplied for your connection.
  3. Save and connect. Sign in with your own Actual Voice account and approve the insights:read permission.
  4. Ask your assistant to list your workspaces and Questions, then load the analysis for the Question you select.

Enter the client secret only in your client's secure connector settings. Keep it out of conversations and shared documents.

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.

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.

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 cannot create Questions, edit data, or run analysis.

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

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 URL including www. Confirm the client ID, secret, and registered callback URL with the Actual Voice team. A client that requires automatic OAuth client registration is not currently supported.
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 client's exact callback URL with the Actual Voice team before connecting. The resource is https://www.actualvoice.ai/mcp and the scope is insights:read. Token requests support client_secret_basic and client_secret_post.

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.