BuildBetter MCP Server - API Reference

This reference provides technical details about the BuildBetter MCP Server’s GraphQL API, including schema types, query operators, and tool specifications.

GraphQL Schema Overview

The BuildBetter MCP server exposes a GraphQL API with the following main types:

interview

Calls, meetings, and conversations

extraction

Customer signals and insights

person

Individual contacts

company

Organizations and companies

Core Types

`interview` (Calls/Meetings)

Represents customer calls, meetings, and conversations.

Key Fields

object

query RecentCalls {
  interview(order_by: {display_ts: desc}, limit: 10) {
    id
    name
    display_ts
    short_summary
    attendees {
      person {
        first_name
        last_name
        email
      }
    }
  }
}

`extraction` (Signals/Insights)

Customer feedback, issues, requests, and other extracted insights.

Key Fields

object

query CustomerIssues {
  extraction(
    where: {
      types: {
        type: {
          name: {_eq: "issue"}
        }
      }
    },
    order_by: {display_ts: desc},
    limit: 20
  ) {
    id
    summary
    sentiment
    call {
      name
      id
    }
  }
}

`person`

Individual contacts (customers and team members).

Key Fields

object

query FindPerson {
  person(
    where: {
      _or: [
        {first_name: {_ilike: "%john%"}},
        {last_name: {_ilike: "%john%"}}
      ]
    }
  ) {
    id
    first_name
    last_name
    email
    company {
      name
    }
  }
}

`company`

Organizations and companies.

Key Fields

object

Query Operators

Filter Operators

_eq

any

Equals

_neq

any

Not equals

_gt

any

Greater than

_gte

any

Greater than or equal

_lt

any

Less than

_lte

any

Less than or equal

_ilike

string

Case-insensitive pattern match (use % for wildcards)

_in

array

In array

_nin

array

Not in array

Logical Operators

_and

array

All conditions must be true

_or

array

Any condition must be true

_not

object

Negation

query ComplexSearch {
  extraction(
    where: {
      _and: [
        {display_ts: {_gte: "2024-01-01"}},
        {sentiment: {_lt: 0}},
        {
          _or: [
            {summary: {_ilike: "%pricing%"}},
            {summary: {_ilike: "%cost%"}}
          ]
        }
      ]
    }
  ) {
    id
    summary
    sentiment
  }
}

MCP Tools Reference

run-query

Execute any GraphQL query.

Parameters:

query (required): GraphQL query string
variables (optional): Query variables object

{
  "tool": "run-query",
  "arguments": {
    "query": "query { interview(limit: 5) { id name } }"
  }
}

list-types

build-query

Generate a query for a specific type.

Parameters:

typeName (required): Name of the GraphQL type
fields (required): Array of field names to include
limit (optional): Number of results
filter (optional): Where clause object

{
  "tool": "build-query",
  "arguments": {
    "typeName": "person",
    "fields": ["id", "first_name", "last_name", "email"],
    "limit": 10,
    "filter": {
      "company_id": 123
    }
  }
}

search-extractions

Search signals with advanced filtering.

Parameters:

phrase (required): Search text
type (optional): Signal type filter
limit (optional): Result limit
personaIds (optional): Array of persona IDs to filter

{
  "tool": "search-extractions",
  "arguments": {
    "phrase": "integration",
    "type": "issue",
    "limit": 20
  }
}

find-fields

Common Query Patterns

# Last 7 days
query RecentData {
  extraction(
    where: {
      display_ts: {_gte: "2024-01-19T00:00:00Z"}
    }
  ) {
    id
    summary
  }
}

# Last 7 days
query RecentData {
  extraction(
    where: {
      display_ts: {_gte: "2024-01-19T00:00:00Z"}
    }
  ) {
    id
    summary
  }
}

query PaginatedResults {
  interview(
    limit: 20,
    offset: 40,
    order_by: {display_ts: desc}
  ) {
    id
    name
  }
}

query DeepQuery {
  company {
    name
    persons {
      first_name
      last_name
      interviews {
        name
        extractions {
          summary
          types {
            type {
              name
            }
          }
        }
      }
    }
  }
}

Rate Limits and Best Practices

Query Depth

Maximum nesting level of 5

Result Size

Maximum 1000 items per query

Batch Queries

Combine multiple queries when possible

Caching

Schema is cached for 30 minutes

Always filter by date when possible to improve performance.

Error Handling

{
  "error": "Invalid or missing API key"
}

For more examples and use cases, see the Complete Guide

GraphQL API

​BuildBetter MCP Server - API Reference

​GraphQL Schema Overview

interview

extraction

person

company

​Core Types

​interview (Calls/Meetings)

​extraction (Signals/Insights)

​person

​company

​Query Operators

​Filter Operators

​Logical Operators

​MCP Tools Reference

​Common Query Patterns

​Rate Limits and Best Practices

Query Depth

Result Size

Batch Queries

Caching

​Error Handling

BuildBetter MCP Server - API Reference

GraphQL Schema Overview

Core Types

`interview` (Calls/Meetings)

`extraction` (Signals/Insights)

`person`

`company`

Query Operators

Filter Operators

Logical Operators

MCP Tools Reference

Common Query Patterns

Rate Limits and Best Practices

Error Handling