Self-Hosted 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. Use this if you're building a custom agent framework that supports MCP — for AI assistants like Claude or Cursor, see the assistant quickstart instead.

Overview

The OriginalVoices MCP server exposes tools that enable AI assistants and agents to gather real-time human insights from Digital Twins. This allows AI applications like Claude Desktop, Cursor, and other MCP-compatible clients to automatically gather human insights when needed, making them more grounded in real human perspectives.

Authentication

All connections to the MCP server require authentication. We support two authentication methods:

• API Key: Create and manage your API keys on the OriginalVoices Platform
• OAuth 2.0: Use a standard Bearer token for OAuth-enabled clients

Credential Security

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

Connection Options

There are two ways to connect to the OriginalVoices MCP server:

Option 1: Streamable HTTP (Recommended)

Connect directly to our hosted MCP server via Streamable HTTP:

https://api.originalvoices.ai/mcp

The Streamable HTTP transport supports both API-Key and OAuth authentication:

• API-Key: X-Api-Key: YOUR_API_KEY
• OAuth: Authorization: Bearer YOUR_ACCESS_TOKEN

To use with Claude Desktop or Cursor, add the following to your MCP configuration:

{
  "mcpServers": {
    "originalvoices": {
      "type": "http",
      "url": "https://api.originalvoices.ai/mcp",
      "headers": {
        "X-Api-Key": "your-api-key"
      }
    }
  }
}

Replace your-api-key with your actual API key from the OriginalVoices Platform.

Option 2: NPM Package

Alternatively, you can run a local MCP server that proxies to our API:

• Package: @originalvoices/mcp-server
• GitHub: ovlabs/mcp-server-originalvoices

To use with Claude Desktop or Cursor, add the following to your MCP configuration:

{
  "mcpServers": {
    "originalvoices": {
      "command": "npx",
      "args": ["@originalvoices/mcp-server"],
      "env": {
        "ORIGINALVOICES_API_KEY": "your-api-key"
      }
    }
  }
}

Replace your-api-key with your actual API key from the OriginalVoices Platform.

Available Tools

The OriginalVoices MCP server provides a tool for gathering human insights:

ask_twins

Ask open-ended questions to a specific audience. Returns raw answers from Digital Twins.

Parameters:

Parameter	Type	Required	Description
audience	string	Yes	Description of the target audience (maps to audiencePrompt)
questions	string[]	Yes	Array of open-ended questions to ask the audience

Returns:

The tool returns raw answers including:

• answers: Array of raw answers from Digital Twins, each containing:
  • answer: The free-text response from the Digital Twin
  • confidence: Score from 0 to 1 representing confidence in the answer correctness

Example:

{
  "audience": "UK, 18-30, fitness enthusiasts",
  "questions": [
    "When purchasing running shoes, what's most important to you?",
    "How often do you replace your running shoes?"
  ]
}

Audience Descriptions

The tool requires 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 X-Api-Key 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)"],
      "questions": ["Array must contain at least 1 element(s)"]
    }
  }
}

Failed Operations

If an operation fails for any reason:

{
  "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

The tool validates input parameters:

• audience: Must be a string between 1 and 255 characters
• questions: Must be an array of strings, each 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 API Quickstart 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.