MCP Server

OriginalVoices provides a Model Context Protocol (MCP) server that allows you to integrate human insights directly into your AI workflows and agentic applications.

Overview

The OriginalVoices MCP server exposes tools that enable AI assistants and agents to gather real-time human insights from Digital Twins. The server uses Server-Sent Events (SSE) for real-time communication and provides two main tools for interacting with audiences.

MCP is a protocol that enables AI assistants to securely access external tools and data sources. By connecting to the OriginalVoices MCP server, your AI applications can automatically gather human insights when needed, making them more grounded in real human perspectives.

Authentication

All connections to the MCP server require authentication using an access token (API key). You can create and manage your API keys on the OriginalVoices Platform.

When connecting to the MCP server, provide your API key via the Authorization header using the Bearer token format:

Authorization: Bearer YOUR_API_KEY

API Key Security

Never commit your API key to version control. Use environment variables or a secrets management service to store your credentials securely.

Connection

The OriginalVoices MCP server is available at:

https://api.originalvoices.ai/mcp/sse

The server uses Server-Sent Events (SSE) for real-time communication. Connect to this endpoint using an MCP-compatible client, providing your API key in the Authorization header.

Example Connection

Most MCP clients will handle the connection automatically. When configuring your MCP client, use:

• Server URL: https://api.originalvoices.ai/mcp/sse
• Authentication: Bearer token with your API key

Available Tools

The OriginalVoices MCP server provides two tools for gathering human insights:

get_insights

Get topic insights for a specific audience and topic. This tool generates a summary, questions, and insights based on Digital Twin responses.

Parameters:

Parameter	Type	Required	Description
audience	string	Yes	The target audience description
topic	string	Yes	The topic to generate insights about

Returns:

The tool returns structured insights including:

• Summary: Overview of how the audience feels about the topic
• Questions: Automatically generated questions asked to the audience
• Insights: Detailed analysis with themes and prevalence data

Example:

{
  "audience": "US, 25-45, tech professionals",
  "topic": "Remote work productivity tools"
}

ask_question

Ask an open-ended question to a specific audience. Returns a summary and themes based on Digital Twin responses.

Parameters:

Parameter	Type	Required	Description
audience	string	Yes	The target audience description
question	string	Yes	The open-ended question to ask the audience

Returns:

The tool returns structured insights including:

• Summary: Summary of responses to your open-ended question
• Themes: Array of key themes identified, each containing:
  • title: The theme name
  • summary: Description of what this theme represents
  • prevalence: How often this theme appeared across all responses (as a percentage)

Example:

{
  "audience": "UK, 18-30, fitness enthusiasts",
  "question": "When purchasing running shoes, what's most important to you?"
}

Audience Descriptions

Both tools require an audience parameter that describes who you want to get insights from. You can describe your audience naturally using plain language that includes any mix of:

• Location: e.g. USA, UK, Australia
• Age range: e.g. 18–34
• Gender: if relevant
• Interests: hobbies, passions, or cultural touchpoints
• Profession or lifestyle: job roles, habits, or mindsets

Example audience descriptions:

• "UK, 18–32, men interested in sports"
• "US, 25–45, tech professionals working remotely"
• "18–30, fitness enthusiasts"

The API interprets your audience description and selects the most relevant Digital Twins that match your criteria.

Error Handling

The MCP server returns structured error responses when something goes wrong. Common error scenarios include:

Unauthorized

If the API key is missing or invalid:

{
  "error": "Unauthorized",
  "message": "API key is required. Provide it via Authorization Bearer header when connecting."
}

or

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

Invalid Arguments

If the provided parameters don't meet validation requirements:

{
  "error": "Invalid arguments",
  "details": {
    "fieldErrors": {
      "audience": ["String must contain at least 1 character(s)"],
      "topic": ["String must contain at least 1 character(s)"]
    }
  }
}

Failed Operations

If an operation fails for any reason:

{
  "error": "Failed to generate insights",
  "message": "Error description here"
}

or

{
  "error": "Failed to ask question",
  "message": "Error description here"
}

All error responses include an isError: true flag to help clients identify and handle errors appropriately.

Parameter Validation

Both tools validate input parameters:

• audience: Must be a string between 1 and 255 characters
• topic (for get_insights): Must be a string between 1 and 255 characters
• question (for ask_question): Must be a string between 1 and 255 characters

If validation fails, the tool returns an error with details about which fields failed validation.

Use Cases

The MCP server is ideal for:

• AI Assistants: Enable your AI assistant to gather human insights when answering questions about consumer preferences, market research, or audience opinions
• Agentic Workflows: Integrate human intelligence into automated workflows that need to understand human perspectives
• Research Tools: Build research applications that can automatically gather insights from target audiences
• Content Creation: Help content creators understand their audience better by asking questions through AI agents

Next Steps

• Learn more about How It Works to understand Digital Twins and the platform
• Check out the Quickstart Guide for REST API usage examples
• Review Question Guidelines to understand what types of questions are allowed
• Explore the API Reference for detailed endpoint documentation

Support

For additional support or questions about the MCP server, please contact support@originalvoices.ai.