BuyerCaddy MCP Server — Quick Connect + Full Reference

The BuyerCaddy MCP server lets AI clients (Claude, Cursor, Windsurf, IDEs) connect directly to BuyerCaddy technographics & buyergraphics.

For most clients, it’s one‑line config — just add the MCP URL and restart the app.

1) Quick Connect (Zero‑Config Clients)

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "buyercaddy": {
      "url": "https://mcp.salescaddy.ai/mcp",
      "type": "http",
 			"headers": {
        "X-Api-Key": "YOUR-API-KEY"
      }
    }
  }
}

Windsurf (Codeium)

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "buyercaddy": {
      "url": "https://mcp.salescaddy.ai/mcp",
      "type": "http",
 			"headers": {
        "X-Api-Key": "YOUR-API-KEY"
      }
    }
  }
}

Claude Desktop

Open claude_desktop_config.json (or MCP config file), add:

{
  "mcpServers": {
    "buyercaddy": {
      "url": "https://mcp.salescaddy.ai/mcp",
      "type": "http",
 			"headers": {
        "X-Api-Key": "YOUR-API-KEY"
      }
    }
  }
}

2) Usage

Once configured and restarted:

Open your client (Claude, Cursor, Windsurf)
Start a new chat
Type a natural prompt like:
“Find customers of Snowflake. Then show related products at hilton.com in the Default cohort.”

The client will call MCP tools automatically, powered by BuyerCaddy.

3) Endpoint & Transport

Transport: Streamable HTTP
URL: https://mcp.buyercaddy.com/mcp
Authentication: None required

4) Client Setup (HTTP transport)

Claude Desktop / IDEs (generic JSON config)

{
  "mcpServers": {
    "buyercaddy": {
      "url": "https://mcp.salescaddy.ai/mcp",
      "type": "http",
 			"headers": {
        "X-Api-Key": "YOUR-API-KEY"
      }
    }
  }
}

Node.js (HTTP MCP client)

const https = require('https');

const API_KEY = "your-key-here";
const HOST = "mcp.salescaddy.ai";
const PATH = "/mcp";

const initData = JSON.stringify({
  jsonrpc: "2.0",
  id: 1,
  method: "initialize",
  params: {
    protocolVersion: "2024-11-05",
    capabilities: {},
    clientInfo: { name: "test-client", version: "1.0.0" }
  }
});

const toolData = JSON.stringify({
  jsonrpc: "2.0",
  id: 2,
  method: "tools/call",
  params: {
    name: "FindCustomersOfProducts",
    arguments: { prompt: "Who uses Snowflake?", size: 5 }
  }
});

const options = {
  hostname: HOST,
  port: 443,
  path: PATH,
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json, text/event-stream',
    'x-api-key': API_KEY
  }
};

console.log(`--- Connecting to remote MCP: ${HOST}${PATH} ---`);

const req = https.request(options, (res) => {
  const sessionId = res.headers['mcp-session-id'];
  
  if (!sessionId) {
    console.error("Error: Could not get mcp-session-id from remote server");
    console.log("Status Code:", res.statusCode);
    console.log("Headers:", res.headers);
    process.exit(1);
  }

  console.log(`Session established. ID: ${sessionId}`);

  // Keep connection open
  res.on('data', () => {});

  const toolOpts = {
    ...options,
    headers: {
      ...options.headers,
      'mcp-session-id': sessionId,
      'Content-Length': Buffer.byteLength(toolData)
    }
  };

  const toolReq = https.request(toolOpts, (toolRes) => {
    let body = '';
    toolRes.on('data', chunk => body += chunk);
    toolRes.on('end', () => {
      console.log("\n--- Tool Result ---");
      try {
        const json = JSON.parse(body);
        if (json.result && json.result.content) {
          json.result.content.forEach(c => console.log(c.text));
        } else {
          console.log(JSON.stringify(json, null, 2));
        }
      } catch (e) {
        console.log("Server response:", body);
      }
      process.exit(0);
    });
  });

  toolReq.write(toolData);
  toolReq.end();
});

req.on('error', (e) => {
  console.error(`Request error: ${e.message}`);
  process.exit(1);
});

req.write(initData);
req.end();

import json
import urllib.request

API_KEY = "your-key-here"
URL = "https://mcp.salescaddy.ai/mcp"

def call_mcp():
    # 1. Initialize
    init_payload = {
        "jsonrpc": "2.0",
        "id": 1,
        "method": "initialize",
        "params": {
            "protocolVersion": "2024-11-05",
            "capabilities": {},
            "clientInfo": {"name": "python-test", "version": "1.0.0"}
        }
    }
    
    headers = {
        "Content-Type": "application/json",
        "Accept": "application/json, text/event-stream",
        "x-api-key": API_KEY
    }

    print(f"--- Connecting to {URL} ---")
    
    req = urllib.request.Request(URL, data=json.dumps(init_payload).encode(), headers=headers, method='POST')
    with urllib.request.urlopen(req) as res:
        session_id = res.headers.get("mcp-session-id")
        if not session_id:
            print("Error: No mcp-session-id found")
            return
        
        print(f"Session established: {session_id}")
        
        # We don't need to keep the stream open in Python urllib for a single subsequent call 
        # as long as the server hasn't timed out the session yet. 
        # But in some cases, the session dies when the connection closes.
        # Let's try sending the tool call.

        tool_payload = {
            "jsonrpc": "2.0",
            "id": 2,
            "method": "tools/call",
            "params": {
                "name": "FindCustomersOfProducts",
                "arguments": {"prompt": "Who uses Snowflake?", "size": 3}
            }
        }
        
        headers["mcp-session-id"] = session_id
        
        tool_req = urllib.request.Request(URL, data=json.dumps(tool_payload).encode(), headers=headers, method='POST')
        with urllib.request.urlopen(tool_req) as tool_res:
            body = tool_res.read().decode()
            print("
--- Tool Result ---")
            try:
                # The response might contain SSE "data: ..." prefix
                if body.startswith("event:"):
                   # Basic parsing of the data line
                   for line in body.split("
"):
                       if line.startswith("data: "):
                           data = json.loads(line[6:])
                           print(json.dumps(data.get("result", {}), indent=2))
                else:
                    print(json.dumps(json.loads(body), indent=2))
            except:
                print(body)

if __name__ == "__main__":
    call_mcp()

using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;
using System.Linq;

namespace McpTest
{
    class Program
    {
        static async Task Main(string[] args)
        {
            const string apiKey = "your-key-here";
            const string url = "https://mcp.salescaddy.ai/mcp";

            using var client = new HttpClient();
            client.DefaultRequestHeaders.Add("x-api-key", apiKey);
            client.DefaultRequestHeaders.Add("Accept", "application/json, text/event-stream");

            Console.WriteLine($"--- Connecting to {url} ---");

            // 1. Initialize
            var initPayload = new
            {
                jsonrpc = "2.0",
                id = 1,
                method = "initialize",
                @params = new
                {
                    protocolVersion = "2024-11-05",
                    capabilities = new { },
                    clientInfo = new { name = "csharp-test", version = "1.0.0" }
                }
            };

            var initContent = new StringContent(JsonSerializer.Serialize(initPayload), Encoding.UTF8, "application/json");
            
            // We use SendAsync with ResponseHeadersRead to keep the SSE connection alive
            using var initResponse = await client.PostAsync(url, initContent);
            
            if (!initResponse.IsSuccessStatusCode)
            {
                Console.WriteLine($"Init failed: {initResponse.StatusCode}");
                return;
            }

            if (!initResponse.Headers.TryGetValues("mcp-session-id", out var sessionIds))
            {
                Console.WriteLine("Error: mcp-session-id header missing");
                return;
            }

            string sessionId = sessionIds.First();
            Console.WriteLine($"Session established: {sessionId}");

            // 2. Call Tool
            var toolPayload = new
            {
                jsonrpc = "2.0",
                id = 2,
                method = "tools/call",
                @params = new
                {
                    name = "FindCustomersOfProducts",
                    arguments = new { prompt = "Who uses Snowflake?", size = 3 }
                }
            };

            var toolRequest = new HttpRequestMessage(HttpMethod.Post, url);
            toolRequest.Headers.Add("x-api-key", apiKey);
            toolRequest.Headers.Add("mcp-session-id", sessionId);
            toolRequest.Content = new StringContent(JsonSerializer.Serialize(toolPayload), Encoding.UTF8, "application/json");

            using var toolResponse = await client.SendAsync(toolRequest);
            string result = await toolResponse.Content.ReadAsStringAsync();

            Console.WriteLine("\n--- Tool Result ---");
            try 
            {
                // Simple check for SSE format or plain JSON
                if (result.StartsWith("event: message")) 
                {
                    var lines = result.Split('\n');
                    var dataLine = lines.FirstOrDefault(l => l.StartsWith("data: "));
                    if (dataLine != null) 
                    {
                        string jsonData = dataLine.Substring(6);
                        Console.WriteLine(jsonData);
                    }
                }
                else 
                {
                    Console.WriteLine(result);
                }
            }
            catch (Exception ex) 
            {
                Console.WriteLine($"Error parsing result: {ex.Message}");
                Console.WriteLine(result);
            }
        }
    }
}

5) Tool Catalog (argument schemas & examples)

Below are all supported tools. Each entry includes: Args Schema, Example Calls (Node/Python), and Sample Response.

1) `company_cohort`

Return peer companies for a domain in a given cohort.

Args Schema

{
  "type": "object",
  "required": ["companyDomain", "cohort"],
  "properties": {
    "companyDomain": { "type": "string", "example": "hilton.com" },
    "cohort": { "type": "string", "enum": ["Default","Defined","Aspirational"] },
    "page": { "type": "integer", "minimum": 0, "default": 0 },
    "size": { "type": "integer", "minimum": 1, "default": 20 }
  }
}

await bc.callTool("company_cohort", { companyDomain: "hilton.com", cohort: "Default", page: 0, size: 10 });

await bc.call_tool("company_cohort", {"companyDomain":"hilton.com","cohort":"Default","page":0,"size":10})

Sample Response

{ "content":[{"domain":"hyatt.com","name":"Hyatt"}], "totalElements":98, "totalPages":5 }

2) `company_feed`

Cursor-based news/activity feed.

Args Schema

{
  "type": "object",
  "required": ["companyDomain"],
  "properties": {
    "companyDomain": { "type": "string" },
    "paginationId": { "type": "string", "nullable": true }
  }
}

await bc.callTool("company_feed", { companyDomain: "hilton.com" });

await bc.call_tool("company_feed", {"companyDomain":"hilton.com"})

Sample Response

{ "paginationId":"eyJvZmZzZXQiOjEwMH0=", "items":[{ "id":"evt_001","title":"Hilton partners..." }] }

3) `company_products_paged`

Installed stack (paged JSON).

Args Schema

{
  "type":"object",
  "required":["companyDomain"],
  "properties":{
    "companyDomain":{"type":"string"},
    "page":{"type":"integer","default":0},
    "size":{"type":"integer","default":20}
  }
}

await bc.callTool("company_products_paged", { companyDomain: "hilton.com", page: 0, size: 20 });

await bc.call_tool("company_products_paged", {"companyDomain":"hilton.com","page":0,"size":20})

Sample Response

{ "content":[{"productId":"prod_office365","productName":"Microsoft 365"}], "totalElements":237, "totalPages":12 }

4) `products_related_in_cohort`

Products related to an anchor product for a company in a cohort.

Args Schema

{
  "type":"object",
  "required":["companyDomain","productId","cohort"],
  "properties":{
    "companyDomain":{"type":"string"},
    "productId":{"type":"string"},
    "cohort":{"type":"string","enum":["Default","Defined","Aspirational"]},
    "page":{"type":"integer","default":0},
    "size":{"type":"integer","default":20}
  }
}

await bc.callTool("products_related_in_cohort", {
  companyDomain:"hilton.com", productId:"prod_office365", cohort:"Default", page:0, size:10
});

await bc.call_tool("products_related_in_cohort", {"companyDomain":"hilton.com","productId":"prod_office365","cohort":"Default","page":0,"size":10})

Sample Response

[{ "id":"prod_slack","name":"Slack" }, { "id":"prod_zoom","name":"Zoom" }]

5) `usage_metrics`

Normalized adoption/intensity/penetration for products within a cohort.

Args Schema

{
  "type":"object",
  "required":["companyDomain","cohort"],
  "properties":{
    "companyDomain":{"type":"string"},
    "cohort":{"type":"string","enum":["Default","Defined","Aspirational"]},
    "vendorDomain":{"type":"string"},
    "productId":{"type":"string"}
  }
}

await bc.callTool("usage_metrics", { companyDomain:"hilton.com", cohort:"Default", vendorDomain:"microsoft.com" });

await bc.call_tool("usage_metrics", {"companyDomain":"hilton.com","cohort":"Default","vendorDomain":"microsoft.com"})

Sample Response

[{ "productId":"prod_office365","adoption":0.68,"intensity":0.74,"penetration":0.71 }]

6) `find_customers_of_products` (AI)

LLM-assisted prospects for products/vendors.

Args Schema

{
  "type":"object",
  "required":["prompt"],
  "properties":{
    "prompt":{"type":"string"},
    "size":{"type":"integer","default":10}
  }
}

await bc.callTool("find_customers_of_products", { prompt:"Who uses Snowflake?", size:10 });

await bc.call_tool("find_customers_of_products", {"prompt":"Who uses Snowflake?","size":10})

Sample Response

[{ "companyDomain":"acme.com","companyName":"Acme Inc.","confidence":0.82 }]

7) `find_techstacks_for_company` (AI)

Summarize tech stack for a company.

Args Schema

{
  "type":"object",
  "required": [],
  "oneOf":[
    { "required":["companyDomain"] },
    { "required":["prompt"] }
  ],
  "properties":{
    "prompt":{"type":"string"},
    "companyDomain":{"type":"string"},
    "size":{"type":"integer","default":20}
  }
}

await bc.callTool("find_techstacks_for_company", { companyDomain:"hilton.com", size:20 });

await bc.call_tool("find_techstacks_for_company", {"companyDomain":"hilton.com","size":20})

Sample Response

[{ "productId":"prod_snowflake","category":"Data Warehouse","confidence":0.86 }]

8) `vendor_products`

All products by a vendor (domain).

Args Schema

{
  "type":"object",
  "required":["vendorDomain"],
  "properties":{
    "vendorDomain":{"type":"string"},
    "productName":{"type":"string"},
    "page":{"type":"integer","default":0},
    "size":{"type":"integer","default":20}
  }
}

await bc.callTool("vendor_products", { vendorDomain:"microsoft.com", page:0, size:10 });

await bc.call_tool("vendor_products", {"vendorDomain":"microsoft.com","page":0,"size":10})

Sample Response

{ "content":[{"id":"prod_office365","name":"Microsoft 365"}], "totalElements":5000, "totalPages":100 }

9) `vendors_search`

Search vendors by name/domain (optionally fuzzy).

Args Schema

{
  "type":"object",
  "required":[],
  "properties":{
    "vendor":{"type":"string","description":"name or domain"},
    "fuzzy":{"type":"boolean","default":false},
    "page":{"type":"integer","default":0},
    "size":{"type":"integer","default":20}
  }
}

await bc.callTool("vendors_search", { vendor:"microsoft.com", fuzzy:false, page:0, size:10 });

await bc.call_tool("vendors_search", {"vendor":"microsoft.com","fuzzy":False,"page":0,"size":10})

Sample Response

{ "content":[{"id":"ven_microsoft","name":"Microsoft","domain":"microsoft.com"}] }

10) `companies_search`

Company search with filters and optional CSV export (server-side action).

Args Schema

{
  "type":"object",
  "required":[],
  "properties":{
    "export":{"type":"boolean","default":false},
    "body":{"type":"object","description":"CompanySearchDTO payload"}
  }
}

await bc.callTool("companies_search", { export:false, body:{ query:"hospitality", countries:["US","DE"] } });

await bc.call_tool("companies_search", {"export":False,"body":{"query":"hospitality","countries":["US","DE"]}})

Sample Response

{ "content":[{"domain":"hilton.com","name":"Hilton"}], "totalElements":237 }

11) `profiles_purchase`

Purchase contact details for profile IDs (billable).

Args Schema

{
  "type":"object",
  "required":["profileIds"],
  "properties":{
    "profileIds":{"type":"array","items":{"type":"string"}}
  }
}

await bc.callTool("profiles_purchase", { profileIds:["prof_001","prof_002"] });

await bc.call_tool("profiles_purchase", {"profileIds":["prof_001","prof_002"]})

Sample Response

{ "results":[{"profileId":"prof_001","status":"purchased","emails":[{"value":"alex@hilton.com"}]}] }

12) `products_in_use`

Deterministically verify product presence for a company.

Args Schema

{
  "type":"object",
  "required":["companyDomain","productIds"],
  "properties":{
    "companyDomain":{"type":"string"},
    "productIds":{"type":"array","items":{"type":"string"}}
  }
}

await bc.callTool("products_in_use", { companyDomain:"hilton.com", productIds:["prod_office365","prod_slack"] });

await bc.call_tool("products_in_use", {"companyDomain":"hilton.com","productIds":["prod_office365","prod_slack"]})

Sample Response

[{ "productId":"prod_office365","inUse":true,"confidence":0.93 }]

13) `categories_list` and `industries_list`

Taxonomy lookups (cacheable).

Args Schema

{ "type":"object", "properties":{} }

await bc.callTool("categories_list", {}); 
await bc.callTool("industries_list", {});

await bc.call_tool("categories_list", {})
await bc.call_tool("industries_list", {})

Sample Response

[{ "id":"cat_crm","name":"CRM" }]

Best Practices (MCP over HTTP)

Connection is very simple — only url and type are needed.
Use reconnection and backoff for network stability.
Cache dictionaries (categories/industries) and firmographics.
Verify AI tool outputs using deterministic tools (e.g., products_in_use, company_products_paged).
Do not log personally identifiable information (PII).

Troubleshooting

Issue	Fix
Connection fails	Ensure type: http is used and URL is `https://mcp.buyercaddy.com/mcp`; check proxy/SSL.
Empty tools list	Your tenant lacks access; contact support.
Long responses	Use smaller `size`, or filter by vendor/product where supported.

Appendix — Discovering runtime schemas

Most MCP clients support listTools(); some also support describeTool(name) to get live JSON Schema for args/results.
Prefer the runtime schema if it disagrees with this document (this doc provides a stable, human-friendly mapping).