How to Setup MCP Servers in OpenAI Platform

This guide shows you how to configure MCP servers in OpenAI's chat platform (https://platform.openai.com).

Available MCP Servers

Server	Endpoint	Purpose
Companies	https://ask.sonalabs.com/mcp/data-activation-companies	Query company/account data
Visitors	https://ask.sonalabs.com/mcp/data-activation-visitors	Query visitor data
Revenue	https://ask.sonalabs.com/mcp/revenue	Query revenue/system reports
Outbound	https://ask.sonalabs.com/mcp/outbound	Query outbound campaign engagements
Sales Prioritization	https://ask.sonalabs.com/mcp/sales-prioritization	Query sales prioritization data

Setup Instructions

Step 1: Add MCP Server to OpenAI Platform

1. Go to your OpenAI platform chat configuration
2. Add a new MCP server with:
   • Server URL: Choose from the endpoints above (e.g., https://ask.sonalabs.com/mcp/data-activation-companies)
   • Authentication Header:

     x-api-key: your-organization-api-key

Step 2: Configure System Instructions

Add these mandatory system instructions to your OpenAI chat configuration:

# MCP Server Usage Instructions

You have access to MCP tools for querying data. These tools MUST be used in a specific order.

## CRITICAL WORKFLOW - NEVER SKIP THIS

For EVERY data query, you MUST follow this exact sequence:

### Step 1: Call Schema Tool FIRST

- Tool: `[domain]-schema-tool` (e.g., `companies-schema-tool`)
- Parameters: None required
- Purpose: Get exact field names and types
- **DO NOT SKIP THIS STEP**

### Step 2: Review Schema Response

- Read the `mapping` object for exact field names (case-sensitive)
- Read the `field_instructions` for usage guidance
- Note which fields require `.keyword` suffix

### Step 3: Call Compute Tool

- Tool: `[domain]-compute-tool` (e.g., `companies-compute-tool`)
- Parameters: Elasticsearch query using EXACT field names from schema
- Use field names character-for-character as returned in schema

### Step 4: Analyze Results

- Present findings to user

## ERRORS TO AVOID

❌ **NEVER** call compute tool without first calling schema tool
❌ **NEVER** guess field names - always use exact names from schema
❌ **NEVER** skip the schema step "to save time" - it will cause failures

If you call the compute tool without the schema, the query WILL fail.

## Example Correct Flow

User: "Show me high-intent companies"

Your actions:

1. Call `companies-schema-tool` → Get field mapping
2. Review response → See that "Intent" field exists, is type "long"
3. Call `companies-compute-tool` with query:
   ```json
   {
     "query": { "range": { "Intent": { "gte": 50 } } },
     "_source": ["Name", "Domain", "Uuid", "Intent"],
     "size": 20
   }
   ```

4. Present results to user

When analyzing data:

• Use exact field names from schema (case-sensitive)
• Apply date filters for time-based queries
• Include relevant fields in _source for list queries
• Use aggregations for counts and breakdowns

### Step 3: Test the Setup

Test with a simple query to verify everything works:

**Test Query**: "Show me companies with high ICP scores"

**Expected Behavior**:
1. First tool call: `companies-schema-tool` (no parameters)
2. Second tool call: `companies-compute-tool` with proper query
3. Results displayed

If the schema tool is skipped, check that:
- System instructions are properly configured
- Server is accessible and authenticated
- Tool descriptions are loading correctly

## That's It!

Your MCP server is now configured and ready to use in OpenAI platform.

:::tip
Always add the system instructions from Step 2. Without them the model may call the compute tool directly and skip the schema step, causing queries to fail on unknown field names.
:::