Skip to main content
v1.0GuidesGuidesAPI ReferenceAPI Reference

OpenAI Integration with MCP Servers

Overview​

This guide explains how to integrate MCP (Model Context Protocol) servers with OpenAI's API using the response format. MCP servers provide specialized tools and context for analyzing business data through OpenAI's function calling capabilities.

What is MCP?​

MCP (Model Context Protocol) is a protocol that allows OpenAI models to interact with external tools and data sources. Each MCP server provides:

  • Tools: Functions that OpenAI can call to query data
  • Context: Domain-specific instructions and schemas
  • Resources: Access to documentation and data structures

Available MCP Servers​

ServerEndpointPurpose
Revenue/mcp/revenueRevenue attribution and conversion analysis
Sales Prioritization/mcp/sales-prioritizationHigh-priority account identification
Outbound/mcp/outboundOutbound campaign analysis
Companies/mcp/data-activation-companiesCompany/account analysis
Visitors/mcp/data-activation-visitorsVisitor behavior analysis
Intent Signals/mcp/intent-signalIntent signal tracking
Marketing Influence/mcp/marketing-influenceMarketing attribution analysis
Reports/mcp/reportGeneral reporting

OpenAI Integration​

Step 1: Get Server Configuration​

First, retrieve the MCP server configuration to get available tools and instructions:

curl -X POST https://ask.sonalabs.com/server/revenue \
  -H "Content-Type: application/json"

Response:

{
  "data": {
    "type": "mcp",
    "server_label": "revenue-server",
    "server_description": "# Milestone Terminology\nThe milestone tool...",
    "server_url": "https://ask.sonalabs.com/mcp/revenue",
    "require_approval": "never"
  }
}

Step 2: Call OpenAI with MCP Server Tools​

Use OpenAI's Chat Completions API with the tools parameter configured with MCP server details:

curl https://api.openai.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-4-turbo-preview",
    "messages": [
      {
        "role": "system",
        "content": "You are a revenue analyst. Use the available tools to query revenue data and answer questions about conversions, attribution, and performance metrics."
      },
      {
        "role": "user",
        "content": "Show me MQL conversions from the last 30 days"
      }
    ],
    "tools": [
      {
        "headers": {
          "x-api-key": "your-mcp-api-key"
        },
        "type": "mcp",
        "server_label": "revenue-server",
        "server_description": "Revenue attribution and conversion analysis server with tools for querying MQLs, SQLs, conversions, and attribution data.",
        "server_url": "https://ask.sonalabs.com/mcp/revenue",
        "require_approval": "never"
      }
    ],
    "tool_choice": "auto"
  }'

OpenAI Response:

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_abc123",
            "type": "function",
            "function": {
              "name": "system_report_compute_tool",
              "arguments": "{\"reportSystemId\":\"1\",\"query\":{\"query\":{\"bool\":{\"filter\":[{\"exists\":{\"field\":\"Signup\"}},{\"range\":{\"Signup\":{\"gte\":\"now-30d/d\"}}}]}},\"size\":0,\"aggs\":{\"total_mqls\":{\"value_count\":{\"field\":\"Signup\"}}}}}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ]
}

Step 3: Execute MCP Tool​

When OpenAI returns a tool call, execute it against the MCP server:

curl -X POST https://ask.sonalabs.com/mcp/revenue \
  -H "Content-Type: application/json" \
  -H "x-api-key: $YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "system-report-compute-tool",
      "arguments": {
        "reportSystemId": "1",
        "query": {
          "query": {
            "bool": {
              "filter": [
                {"exists": {"field": "Signup"}},
                {"range": {"Signup": {"gte": "now-30d/d"}}}
              ]
            }
          },
          "size": 0,
          "aggs": {
            "total_mqls": {
              "value_count": {"field": "Signup"}
            }
          }
        }
      }
    }
  }'

MCP Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Total MQLs in last 30 days: 150\n\nAggregations:\n- total_mqls: 150"
      }
    ]
  }
}

Step 4: Send Results Back to OpenAI​

Send the tool result back to OpenAI to get the final response:

curl https://api.openai.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-4-turbo-preview",
    "messages": [
      {
        "role": "system",
        "content": "You are a revenue analyst..."
      },
      {
        "role": "user",
        "content": "Show me MQL conversions from the last 30 days"
      },
      {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_abc123",
            "type": "function",
            "function": {
              "name": "system_report_compute_tool",
              "arguments": "{\"reportSystemId\":\"1\",\"query\":{...}}"
            }
          }
        ]
      },
      {
        "role": "tool",
        "tool_call_id": "call_abc123",
        "content": "Total MQLs in last 30 days: 150"
      }
    ]
  }'

Final OpenAI Response:

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "In the last 30 days, you had **150 MQL conversions**. This represents leads that reached the Marketing Qualified Lead milestone (Signup) during this period."
      },
      "finish_reason": "stop"
    }
  ]
}

Authentication​

OpenAI API Key​

Get your OpenAI API key from: https://platform.openai.com/api-keys

export OPENAI_API_KEY="sk-..."

MCP Server API Key​

Contact your administrator to obtain your MCP API key.

export YOUR_API_KEY="your-mcp-api-key"

Use both keys in your integration:

  • OpenAI API: Authorization: Bearer $OPENAI_API_KEY
  • MCP Server: x-api-key: $YOUR_API_KEY

Rate Limiting​

OpenAI Limits​

MCP Server Limits​

  • Rate Limit: 100 requests per minute per organization
  • Timeout: 30 seconds per request
  • Max Payload: 10MB