Pearl

You can run the Pearl MCP Server to access Pearl’s AI assistants and human experts through a standardized MCP interface. This server supports both local stdio connections and remote MCP transport, enabling you to integrate Pearl’s capabilities with MCP clients and workflows.

How to use

Choose how you want to connect your MCP client to the Pearl MCP Server. For local development and testing, use the stdio transport so your client communicates directly with the server process. For remote access, point clients to the hosted MCP endpoint or use an auxiliary bridge if your client lacks native MCP support.

You can interact with both AI and human expert services. Use the AI-Expert mode for AI-assisted human expert support, or the Expert mode for direct human expert assistance. You can start conversations, track conversation history, and check the status of ongoing sessions to keep context across exchanges.

To begin a session and list available tools, connect your MCP client and initialize the session. From there, you can call either AI-focused tools or expert tools to obtain insights, explanations, or validated expertise as needed.

How to install

Prerequisites you need before installing the server are Python 3.12 or higher, a Pearl API key, and a package manager such as pip.

Step by step, follow these commands to set up and run the server locally:

# 1. Clone the repository
git clone https://github.com/Pearl-com/pearl_mcp_server.git
cd pearl_mcp_server

# 2. Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# 3. Install dependencies
pip install -e .

# 4. Create a configuration file with your API key
# Create a .env file in the src directory
echo 'PEARL_API_KEY=your-api-key-here' > src/.env

# 5. Run the server locally (stdio transport by default)
pearl-mcp-server --api-key your-api-key

If you prefer to run the server with the SSE transport on a custom port, use this command instead:

pearl-mcp-server --api-key your-api-key --transport sse --port 8000

Additional configuration and access

You can also connect to Pearl’s hosted MCP server from any MCP client without installing the Python application locally. The hosted endpoint is available at the following URL.

Hosted MCP URL: https://mcp.pearl.com/mcp

Connecting with MCP clients

Local connections use stdio transport, while remote connections can be bridged via an MCP bridge if your client does not support direct MCP endpoints.

Troubleshooting and notes

If you encounter authentication or connection issues, ensure your Pearl API key is correctly set in the environment variable PEARL_API_KEY and that the server process is running with access to this key.

For using a bridge or remote client, verify the bridge is configured to connect to the hosted MCP URL and that any authentication keys are valid and current.

Available tools

ask_pearl_expert

AI-assisted human expert support with context-aware routing for complex topics that require expert verification.

ask_expert

Direct human expert assistance for complex or sensitive topics.

get_conversation_status

Check the status of an active conversation using a session identifier.

get_conversation_history

Retrieve the full history of a given conversation by session identifier.