Repository files navigation

An OpenAI Responses API integration with Pearl API via MCP

This sample application extends theOpenAI Responses Starter App to demonstrate how to integrate OpenAI'sresponses API with thePearl MCP Server, enabling your AI agents to seamlessly escalate queries toreal human experts.

• Integrated withPearl's Remote MCP Server via OpenAI’s Responses API MCP tool interface
• Automatically escalates user questions to human Experts using theaskExpert tool
• Supports secure authentication with Pearl via bearer token
• Real-time response streaming with AI + human blended answers

Clone this repo and install dependencies:

git clone https://github.com/Pearl-com/openai-pearl-mcp-demo.gitcd openai-pearl-mcp-demonpm install

Create a.env file in the root with the following variables:

OPENAI_API_KEY=your-openai-api-keyPEARL_API_KEY=your-pearl-api-key

This app leverages OpenAI's hostedModel Context Protocol (MCP) integration to connect with Pearl’s MCP server. The server provides tools likeaskExpert that route queries to real, credentialed professionals.

graph TD    A[AI Encounter] --> B{Recognize Need for Expert};    B -- Human Input Required --> C[Invoke via MCP];    C -- Context & Question --> D[Route to Expert];    D -- Request Forwarded --> E[Expert Input];    E -- Review/Answer Provided --> F[Return to AI];    F -- Structured Expert Response --> G[AI Response];    style A fill:#D4E6F1,stroke:#3498DB,stroke-width:2px,color:#2C3E50;    style B fill:#F9E79F,stroke:#F1C40F,stroke-width:2px,color:#2C3E50;    style C fill:#D4E6F1,stroke:#3498DB,stroke-width:2px,color:#2C3E50;    style D fill:#D4E6F1,stroke:#3498DB,stroke-width:2px,color:#2C3E50;    style E fill:#D4E6F1,stroke:#3498DB,stroke-width:2px,color:#2C3E50;    style F fill:#F9E79F,stroke:#F1C40F,stroke-width:2px,color:#2C3E50;    style G fill:#D4E6F1,stroke:#3498DB,stroke-width:2px,color:#2C3E50;

Here’s how thetools block is defined inside theopenai.responses.create() call:

constevents=awaitopenai.responses.create({model:MODEL,input:messages,tools:[{type:"mcp",server_label:"pearl-api-mcp-server",server_url:"https://mcp.pearl.com/mcp",require_approval:"never",allowed_tools:["askExpert"],headers:{"X-API-KEY":`${process.env.PEARL_API_KEY}`,},},],stream:true,parallel_tool_calls:false,instructions:SYSTEM_PROMPT,});

Pearl MCP server usesApi Key authentication, passed via theX-API-KEY header. ContactPearl to obtain your API key.

A user asks:

“Is this clause legally binding?”

The AI recognizes the need for expert legal input, invokesaskExpert via the MCP interface, and Pearl routes the query to a certified lawyer. The expert's response is streamed back and incorporated into the AI's final output.

ThePearl MCP Server offers human expertise as a tool, making it possible to enrich AI-driven workflows with real-time, on-demand access to professionals in law, finance, medicine, automotive, and more.

Pearl MCP is:

• Fully compliant with OpenAI’s MCP protocol
• Secure (Bearer tokens)
• Scalable across categories
• Built on Cloudflare Workers for ultra-low latency

Here’s an example of the Pearl MCP tool call in action:

• OpenAI Responses API
• Next.js (or React if applicable)
• Pearl MCP Server
  (hosted athttps://mcp.pearl.com/mcp)