Pearl MCP Server for AI and Expert Services

Overview

Pearl MCP Server implements the Model Context Protocol (MCP) to expose Pearl’s AI assistants and human expert services through a single, consistent interface. Developers and MCP-compatible clients (for example, Claude Desktop, Cursor, and other tools that support MCP) can connect to the server to route queries to either AI-driven responses, human experts, or hybrid AI-assisted expert workflows. The server standardizes session handling, conversation history, and transport options so client integrations remain simple and predictable.

This server is useful when you want a drop-in MCP endpoint that can switch between automated agent responses and human-in-the-loop verification, or when you need to give multiple MCP clients unified access to Pearl’s expert categories and conversational state management.

Features

• Support for stdio and Server-Sent Events (SSE) transports
• Integration with Pearl API for AI responses and expert routing
• Stateful sessions and conversation history tracking
• Two interaction modes:
  • AI-Expert: AI generates suggestions and a human expert validates/augments them
  • Expert: direct routing to a human expert
• Tools for querying conversation status and retrieving history
• Works locally (stdio) or as a hosted endpoint (SSE)

Installation / Configuration

Prerequisites:

• Python 3.12+
• Pearl API key (contact Pearl to obtain)
• pip

Clone and install:

git clone https://github.com/Pearl-com/pearl_mcp_server.git
cd pearl_mcp_server
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e .

Set API key (example .env in src/ or project root):

# .env
PEARL_API_KEY=your-api-key-here

Run the server locally:

# stdio transport (default)
pearl-mcp-server --api-key your-api-key

# SSE transport on a custom port
pearl-mcp-server --api-key your-api-key --transport sse --port 8000

Pearl also provides a hosted endpoint that can be used directly by MCP clients: https://mcp.pearl.com/mcp

Available Tools

The MCP server exposes a small set of tools for interacting with Pearl services:

• ask_pearl_expert
  • AI-assisted human expert support (AI + expert verification)
  • Accepts the same parameters as ask_pearl_ai (prompt, session_id, metadata)
• ask_expert
  • Direct human expert assistance (no AI pre-processing)
  • Same parameters as ask_pearl_ai
• get_conversation_status
  • Check current session status
  • Parameter: session_id
• get_conversation_history
  • Fetch the full conversation transcript for a session
  • Parameter: session_id

Use these programmatically through MCP client messages or via integrated MCP tooling in supported clients.

Expert Categories

The server routes queries to relevant experts automatically based on context. Major categories include:

You typically do not need to specify a category; Pearl’s routing will select the best match for your query.

Connecting with MCP Clients

Example local stdio MCP client config (JSON):

{
  "pearl-mcp-server": {
    "type": "stdio",
    "command": "pearl-mcp-server",
    "args": ["--api-key", "your-api-key"],
    "env": {
      "PEARL_API_KEY": "your-api-key"
    }
  }
}

For clients that cannot connect to a remote SSE endpoint directly, use mcp-remote as a bridge:

{
  "mcpServers": {
    "pearl-remote": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.pearl.com/sse"]
    }
  }
}

Common troubleshooting:

• Clear mcp-remote credentials: rm -rf ~/.mcp-auth
• Check client logs for connectivity details

Python example (stdio client pattern):

import asyncio
from mcp.client.session import ClientSession
from mcp.client.stdio import StdioServerParameters, stdio_client

async def main():
    async with stdio_client(
        StdioServerParameters(command="pearl-mcp-server", args=["--api-key", "your-api-key"])
    ) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            # use session to send/receive MCP messages

asyncio.run(main())

Use Cases

• Agentic AI with verification: Use ask_pearl_expert to have AI generate a draft answer and a qualified human expert verify or correct it before finalization (ideal for high-stakes domains such as healthcare or legal).
• Human-in-the-loop escalations: Start with automated responses; if confidence is low, escalate the conversation to a live expert via ask_expert.
• Multi-client access: Expose a single MCP endpoint for multiple desktop or editor integrations (Claude Desktop, Cursor) so teams have consistent expert/AI access across tools.
• Session-driven workflows: Maintain long-lived session state and conversation history for continuity across investigator handoffs or follow-up queries.

Additional Notes

• Session state and conversation transcripts are accessible via get_conversation_history and get_conversation_status for auditability and workflow integrations.
• Use SSE transport for hosted deployments and stdio for local or embedded workflows.
• Refer to the GitHub repository for the full source, contribution guidelines, and up-to-date examples: https://github.com/Pearl-com/pearl_mcp_server