pearl_mcp_server

Pearl MCP Server exposes Pearl's AI assistants and human experts through the MCP interface. It supports both stdio and SSE transports, enabling local development with stdio or remote interactions via SSE. The server exposes tools for AI-assisted expert support and direct expert access, including the ability to check conversation status and retrieve full conversation history. To use it, obtain a Pearl API key and start the server in your environment; then connect with an MCP client and call tools such as ask_pearl_expert for AI-assisted human expertise, or ask_expert for direct human assistance. You can also query get_conversation_status and get_conversation_history to manage and inspect ongoing sessions. The Expert categories span medical, legal, technical, education, and lifestyle topics, with Pearl routing the query to the most appropriate expert type based on context. With session management, you can maintain continuity across messages within a single conversation.

For local development, run the server and connect via stdio (default) or SSE transport. For remote usage, you can rely on Pearl’s hosted MCP endpoint to connect directly from clients that support remote MCP servers. The included tooling lets you perform complex inquiries, track conversation progress, and retrieve complete histories to maintain context across interactions.

Prerequisites:

• Python 3.12 or higher
• Pearl API Key (obtain from Pearl)
• pip (or uv) package manager

Installation steps:

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
# macOS/Linux
source .venv/bin/activate
# Windows
.venv\Scripts\activate

3. Install the package in editable mode

pip install -e .

4. Create a configuration file with your Pearl API key (see environment variables below).

PEARL_API_KEY=your-api-key-here

5. Run the server locally

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

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

Notes:

• If you prefer remote hosting, you can also use Pearl's hosted MCP server endpoint and connect with an MCP client that supports remote endpoints.

Environment variables and configuration tips:

• PEARL_API_KEY is required for authenticating with Pearl services.
• The server supports both stdio and SSE transports; use the --transport flag to switch modes and --port to specify a custom port for SSE.
• When using remote connections via mcp-remote, you can point clients to Pearl's hosted endpoint at https://mcp.pearl.com/mcp or the SSE endpoint.
• For development troubleshooting, you can access logs and verify connectivity through standard MCP client debugging steps.

Common issues:

• Invalid or missing API key: ensure PEARL_API_KEY is set in the environment where the server runs.
• Port conflicts for SSE transport: choose an unused port with --port.
• Dependency installation failures: ensure you are using Python 3.12+, and re-create the virtual environment if needed.

Configuration options:

• Transport: stdio or sse (via --transport)
• Port: customize with --port for SSE
• API key: supplied via --api-key or PEARL_API_KEY environment variable