API Reference
Start typing to search…

BuyerCaddy MCP Server - Real Data

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.buyercaddy.com/mcp",
      "type": "http"
    }
  }
}

Windsurf (Codeium)

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

{
  "mcpServers": {
    "buyercaddy": {
      "url": "https://mcp.buyercaddy.com/mcp",
      "type": "http"
    }
  }
}

Claude Desktop

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

{
  "mcpServers": {
    "buyercaddy": {
      "url": "https://mcp.buyercaddy.com/mcp",
      "type": "http"
    }
  }
}

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": {
      "type": "http",
      "url": "https://mcp.buyercaddy.com/mcp"
    }
  }
}

Node.js (HTTP MCP client)

import { HTTPClient } from "@modelcontextprotocol/sdk/client/http";

const bc = new HTTPClient({
  url: "https://mcp.buyercaddy.com/mcp"
});

await bc.connect();
console.log(await bc.listTools());
// Example call
const res = await bc.callTool("find_customers_of_products", { prompt: "Who uses Snowflake?", size: 10 });
console.log(res);
from mcp_http import ClientHTTP

bc = ClientHTTP("https://mcp.buyercaddy.com/mcp")
await bc.connect()
print(await bc.list_tools())
res = await bc.call_tool("find_customers_of_products", {"prompt": "Who uses Snowflake?", "size": 10})
print(res)
// Use your MCP HTTP client; no headers required

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_search

People search with filters (export requires attribution).

Args Schema

{
  "type":"object",
  "required":[],
  "properties":{
    "export":{"type":"boolean","default":false},
    "body":{"type":"object","description":"Profiles search payload"}
  }
}
await bc.callTool("profiles_search", { export:false, body:{ titles:["VP Data"], countries:["US"] } });
await bc.call_tool("profiles_search", {"export":False,"body":{"titles":["VP Data"],"countries":["US"]}})

Sample Response

{ "content":[{"id":"prof_001","fullName":"Alex Johnson","title":"VP Data"}] }

12) 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":"[email protected]"}]}] }

13) profiles_details

Fetch a full profile by ID (returns contacts if owned).

Args Schema

{
  "type":"object",
  "required":["profileId"],
  "properties":{ "profileId":{"type":"string"} }
}
await bc.callTool("profiles_details", { profileId:"prof_001" });
await bc.call_tool("profiles_details", {"profileId":"prof_001"})

Sample Response

{ "id":"prof_001","fullName":"Alex Johnson","emails":[{"value":"[email protected]"}] }

14) 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 }]

15) 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

IssueFix
Connection failsEnsure type: http is used and URL is https://mcp.buyercaddy.com/mcp; check proxy/SSL.
Empty tools listYour tenant lacks access; contact support.
Long responsesUse 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).