Pearl MCP Server

Pearl MCP Server

What is Pearl MCP Server about?

Pearl MCP Server provides a Model Context Protocol (MCP) endpoint that bridges Pearl's advanced AI assistants and human expert network with any MCP‑compatible client (e.g., Claude Desktop, Cursor). It abstracts the underlying Pearl API behind a simple transport layer (stdio or Server‑Sent Events) so applications can request AI‑only answers, AI‑augmented expert assistance, or direct human expert help.

How to use Pearl MCP Server?

1. Install the Python package and create a virtual environment.
2. Configure the .env file with your PEARL_API_KEY.
3. Run the server:
   • StdIO (default): pearl-mcp-server --api-key <your-key>
   • SSE: pearl-mcp-server --api-key <your-key> --transport sse --port 8000
4. Connect a client:
   • Local stdio: configure the client to launch pearl-mcp-server with the API key.
   • Remote (hosted by Pearl) or through mcp-remote (Node.js) for clients that require an HTTP endpoint.

Key features of Pearl MCP Server

• Supports both stdio and SSE transports.
• Seamless integration with Pearl API for AI and expert workflows.
• Session‑aware conversation handling (continuous context, history retrieval).
• Three interaction modes: AI‑only, AI‑Expert, and Expert.
• Automatic routing to the appropriate expert category based on query context.
• Ready‑to‑use tools such as ask_pearl_ai, ask_pearl_expert, ask_expert, get_conversation_status, and get_conversation_history.

Use cases of Pearl MCP Server

• Developer tools: embed AI‑assisted code suggestions or debugging help inside IDEs that support MCP.
• Customer support: provide instant AI replies, with optional escalation to vetted human experts for complex tickets.
• Healthcare & legal portals: allow users to ask domain‑specific questions and receive answers from qualified professionals via the expert category routing.
• Educational platforms: deliver tutoring assistance, automatically selecting subject‑matter experts.
• Personal assistants: integrate with voice or chat agents that need to switch between automated and expert‑verified responses.

FAQ from the Pearl MCP Server

Q: Do I need a Pearl account to run the server? A: Yes, you must obtain a Pearl API key from the Pearl contact page.

Q: Can I run the server publicly? A: The repository supplies a local implementation; Pearl also offers a hosted MCP endpoint (https://mcp.pearl.com/mcp). For public exposure you would need to host the Python server behind your own HTTPS reverse proxy.

Q: Which transport should I choose? A: Use stdio for local desktop clients; choose SSE when a network‑accessible HTTP endpoint is required.

Q: How are expert categories selected? A: The Pearl API analyzes the query context and automatically routes the request to the most relevant expert domain (e.g., medical, legal, technical).

Q: Is the API key exposed to clients? A: No. The server handles the API key internally; clients only interact with the MCP layer.

Pearl MCP Server

A Model Context Protocol (MCP) server implementation that exposes Pearl's AI and Expert services through a standardized interface. This server allows MCP clients like Claude Desktop, Cursor, and other MCP-compatible applications to interact with Pearl's advanced AI assistants and human experts.

Features

• Support for both stdio and SSE transports
• Integration with Pearl API for AI and expert assistance
• Session management for continuous conversations
• Multiple interaction modes:
  • AI-only mode for quick automated responses
  • AI-Expert mode for AI-assisted human expert support
  • Expert mode for direct human expert assistance
• Conversation history tracking
• Stateful session management

Prerequisites

• Python 3.12 or higher
• Pearl API Key (Contact Pearl to obtain your API key)
• pip or uv package manager

Installation

1. Clone the repository:

git clone https://github.com/Pearl-com/pearl_mcp_server.git
cd pearl_mcp_server

2. Create a virtual environment and activate it:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install dependencies:

pip install -e .

Configuration

1. Create a .env file in the src directory:

PEARL_API_KEY=your-api-key-here

Running the Server

Local Development

Start the server using either stdio (default) or SSE transport:

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

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

Using Remote Server

Pearl provides a hosted MCP server at:

https://mcp.pearl.com/mcp

This can be used directly with any MCP client without installing the Python application locally.

Available Tools

The server provides the following tools:

1. ask_pearl_ai

   • Quick AI-only responses without human review
   • Best for general inquiries and non-critical situations
   • Parameters:
     • question: The user's query
     • chat_history (optional): Previous conversation context
     • session_id (optional): For continuing conversations

2. ask_pearl_expert

   • AI-assisted human expert support
   • Best for complex topics requiring expert verification
   • Parameters: Same as ask_pearl_ai

3. ask_expert

   • Direct human expert assistance
   • Best for complex or sensitive topics
   • Parameters: Same as ask_pearl_ai

4. get_conversation_status

   • Check the status of an active conversation
   • Parameter: session_id

5. get_conversation_history

   • Retrieve full conversation history
   • Parameter: session_id

Expert Categories

Pearl's MCP server provides access to a wide range of expert categories. The appropriate expert category is automatically determined by Pearl's API based on the context of your query, ensuring you're connected with the most relevant expert for your needs.

Here are the main categories of expertise available:

• Medical & Healthcare

  • General Medicine
  • Dental Health
  • Mental Health
  • Nutrition & Diet
  • Fitness & Exercise
  • Veterinary Medicine

• Legal & Financial

  • Legal Advice
  • Tax Consultation
  • Financial Planning
  • Business Law
  • Employment Law
  • Real Estate Law

• Technical & Professional

  • Software Development
  • IT Support
  • Computer Repair
  • Electronics
  • Mechanical Engineering
  • Home Improvement

• Education & Career

  • Academic Tutoring
  • Career Counseling
  • Resume Writing
  • Test Preparation
  • College Admissions
  • Professional Development

• Lifestyle & Personal

  • Relationship Advice
  • Parenting
  • Pet Care
  • Personal Styling
  • Interior Design
  • Travel Planning

Each expert category can be accessed through the ask_expert or ask_pearl_expert tools. You don't need to specify the category - simply describe your question or problem, and Pearl's AI will automatically route your request to the most appropriate expert type based on the context.

Connecting with MCP Clients

Local Connection (stdio transport)

For connecting to a local MCP server using stdio transport, add the following configuration to your MCP client:

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

Remote Connection using mcp-remote

Some MCP clients don't support direct connection to remote MCP servers. For these clients, you can use the mcp-remote package as a bridge:

1. Prerequisites:

   • Node.js 18 or higher
   • npm (Node Package Manager)

2. Configuration for remote server:

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

3. Configuration file locations:

   • Claude Desktop:
     • Windows: %APPDATA%\Claude\claude_desktop_config.json
     • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Cursor: ~/.cursor/mcp.json
   • Windsurf: ~/.codeium/windsurf/mcp_config.json

4. Additional Options:

   • Force latest version: Add @latest to npx command

   "args": ["mcp-remote@latest", "https://mcp.pearl.com/sse"]
   

5. Troubleshooting:

   • Clear stored credentials: rm -rf ~/.mcp-auth
   • View logs:
     • Windows (PowerShell): Get-Content "$env:APPDATA\Claude\Logs\mcp.log" -Wait -Tail 20
     • macOS/Linux: tail -n 20 -F ~/Library/Logs/Claude/mcp*.log
   • Test connection: npx mcp-remote-client https://mcp.pearl.com/sse

Custom Python Client

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

async def main():
    # For stdio transport
    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()
            
            # List available tools
            tools = await session.list_tools()
            print(tools)
            
            # Call Pearl AI
            result = await session.call_tool(
                "ask_pearl_ai", 
                {
                    "question": "What is MCP?",
                    "session_id": "optional-session-id"
                }
            )
            print(result)

asyncio.run(main())

API Key

To obtain a Pearl API key for using this server:

1. Visit Pearl Contact Page
2. Request an API key for MCP server integration
3. Follow the provided instructions to complete the registration process

Keep your API key secure and never commit it to version control.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.