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

​
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

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 } }"
  }
}
Get all available GraphQL types.Parameters: NoneReturns: Array of type names
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 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
  }
}
Get available fields for a type.Parameters:
  • typeName (required): GraphQL type name
Returns: List of fields with their types

​
Common Query Patterns

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

​
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