> ## Documentation Index
> Fetch the complete documentation index at: https://docs.buildbetter.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Complete User Guide

> Everything you need to know about using BuildBetter MCP Server

# BuildBetter MCP Server - Complete Guide

<Info>
  This guide covers everything you need to know about the BuildBetter MCP Server, from setup to what you can ask and troubleshooting.
</Info>

## Overview

The BuildBetter MCP Server lets AI assistants like Claude and ChatGPT securely access your BuildBetter data. Once connected, you can ask questions about your calls, customer feedback, contacts, and companies in plain language — the assistant handles everything behind the scenes.

<CardGroup cols={2}>
  <Card title="Read-Only" icon="lock">
    Your data can never be modified through the MCP server
  </Card>

  <Card title="No Local Setup" icon="cloud">
    Nothing to install — just add a URL and sign in
  </Card>

  <Card title="Sign In With BuildBetter" icon="right-to-bracket">
    Uses your existing BuildBetter account
  </Card>

  <Card title="Live Data" icon="bolt">
    Always reflects your latest BuildBetter data
  </Card>
</CardGroup>

## Getting Started

### Prerequisites

<Check>
  * A **BuildBetter account**
  * A supported AI client: **Claude Desktop**, **Claude Code**, **Cursor**, or **ChatGPT**
</Check>

### How Sign-In Works

When you first connect, your AI client opens a browser window where you sign in with your BuildBetter account. After that, you're connected — no API keys to manage or rotate.

**SSO-First Sign-In:** The MCP login page offers an SSO-first experience. Enter your work email and you'll be routed to the right identity provider automatically when one is configured for your organization. You can still fall back to email/password if needed.

**Server-Side Encrypted Config:** Your MCP server configuration is stored server-side with encryption (no more browser local storage). Existing sessions were migrated automatically — sign-in is simpler and your config survives across browsers and devices.

### Connection URL

You can connect using either:

* `https://mcp.buildbetter.app` (recommended)
* `https://mcp.buildbetter.app/mcp` (also supported for backward compatibility)

Both paths route to the same MCP server.

### Supported Scopes

MCP supports the following OAuth scopes:

* **User scope (default):** Access scoped to your BuildBetter user — recommended for individual setups in Claude, Cursor, ChatGPT, etc.
* **`service_account` scope:** For programmatic / non-interactive use cases where the client should authenticate as an organization-level service account rather than an individual user. Useful for shared automation.

## Setup Instructions

### Claude Desktop

<Steps>
  <Step title="Open Settings">
    In Claude Desktop, go to **Settings > Connectors** and click **Add Custom Connector**.
  </Step>

  <Step title="Add BuildBetter">
    Enter a name (e.g., "BuildBetter") and paste the following URL:

    ```
    https://mcp.buildbetter.app
    ```

    Then click **Add**.
  </Step>

  <Step title="Sign In">
    Ask Claude something about your BuildBetter data. On first use, your browser will open to sign in.
  </Step>
</Steps>

### Claude Code

<Steps>
  <Step title="Add the Server">
    ```bash theme={null}
    claude mcp add buildbetter --transport http https://mcp.buildbetter.app
    ```
  </Step>

  <Step title="Sign In">
    On first use, your browser will open to sign in with your BuildBetter account.
  </Step>
</Steps>

### Cursor

<Steps>
  <Step title="Open MCP Settings">
    Go to **Cursor Settings > MCP** and click **Add new MCP server**.
  </Step>

  <Step title="Configure">
    * **Type:** HTTP
    * **URL:** `https://mcp.buildbetter.app`
  </Step>

  <Step title="Sign In">
    On first use, you'll be prompted to sign in with your BuildBetter account.
  </Step>
</Steps>

### ChatGPT

<Steps>
  <Step title="Add MCP Server">
    In ChatGPT, navigate to MCP server settings and add:

    ```
    https://mcp.buildbetter.app
    ```
  </Step>

  <Step title="Sign In">
    You'll be redirected to sign in with your BuildBetter account.
  </Step>
</Steps>

## What You Can Ask About

Once connected, just ask questions in plain language. Here's what data is available:

<AccordionGroup>
  <Accordion title="Calls & Meetings" icon="phone">
    Access your recorded calls, meetings, and conversations — including summaries, participants, and timestamps.

    **Example questions:**

    * "Show me my 10 most recent customer calls"
    * "Find all calls with Acme Corp from this month"
    * "Summarize yesterday's demo call with the engineering team"
    * "Which calls had the most participants this week?"
  </Accordion>

  <Accordion title="Customer Signals & Feedback" icon="chart-line">
    Search through extracted insights from your conversations — issues, feature requests, praise, complaints, and more.

    **Example questions:**

    * "What issues did customers raise this week?"
    * "Show me all feature requests from the last 30 days"
    * "Find negative feedback about our onboarding process"
    * "What are customers praising us for?"
  </Accordion>

  <Accordion title="People & Contacts" icon="address-book">
    Look up customers and team members, and see their associated calls and feedback.

    **Example questions:**

    * "Find all conversations involving John Smith"
    * "Who are our most active customer contacts?"
    * "Show me all feedback from people at Acme Corp"
  </Accordion>

  <Accordion title="Companies & Accounts" icon="building">
    Access company information and see all associated people, calls, and signals.

    **Example questions:**

    * "Show me everything we know about Acme Corp"
    * "Which companies have raised the most issues recently?"
    * "List all companies we've talked to this quarter"
  </Accordion>

  <Accordion title="Documents" icon="file-lines">
    Search and retrieve AI-generated documents and imported content like Notion pages.

    **Example questions:**

    * "Find all documents about our onboarding process"
    * "Show me the latest competitive analysis doc"
    * "Search for documents imported from Notion"
  </Accordion>

  <Accordion title="Knowledge Base" icon="book">
    Browse and search your internal knowledge base wiki pages.

    **Example questions:**

    * "What's in our knowledge base about pricing?"
    * "Show me the custom context page"
    * "Find knowledge pages about workflows"
  </Accordion>

  <Accordion title="Advanced GraphQL Queries" icon="code">
    Run custom queries against the full BuildBetter data model for advanced use cases.

    **Example questions:**

    * "Query the last 10 interviews with their tags"
    * "What GraphQL types are available?"
    * "Show me all fields on the extraction type"
  </Accordion>
</AccordionGroup>

<Tip>
  For a complete list of all 21 tools with parameters and examples, see the [Tool Reference](/pages/MCP/tool-reference).
</Tip>

## Use Cases by Team

### Customer Success

<CardGroup cols={1}>
  <Card title="Weekly Customer Health Reports" icon="heartbeat">
    > "Show me all critical issues mentioned by Enterprise customers in the last 7 days"
  </Card>

  <Card title="Account Reviews" icon="building">
    > "Find all conversations with Acme Corp and summarize their main pain points"
  </Card>

  <Card title="Churn Risk Analysis" icon="triangle-exclamation">
    > "Identify customers who've expressed frustration in recent calls"
  </Card>
</CardGroup>

### Product Management

<CardGroup cols={1}>
  <Card title="Feature Request Tracking" icon="sparkles">
    > "List all feature requests mentioned in the last month, grouped by theme"
  </Card>

  <Card title="User Feedback Analysis" icon="comments">
    > "Find all feedback about our onboarding process"
  </Card>

  <Card title="Competitive Intelligence" icon="chess">
    > "Show mentions of competitors in customer calls"
  </Card>
</CardGroup>

### Engineering

<CardGroup cols={1}>
  <Card title="Bug Report Aggregation" icon="bug">
    > "Find all technical issues mentioned by customers this week"
  </Card>

  <Card title="Integration Feedback" icon="plug">
    > "Search for problems users are having with our API"
  </Card>

  <Card title="Performance Complaints" icon="gauge-high">
    > "List all mentions of slow performance or timeouts"
  </Card>
</CardGroup>

### Leadership

<CardGroup cols={1}>
  <Card title="Strategic Insights" icon="compass">
    > "Summarize the top 5 themes from customer conversations this quarter"
  </Card>

  <Card title="Market Trends" icon="chart-mixed">
    > "What new use cases are customers asking about?"
  </Card>

  <Card title="Customer Sentiment" icon="face-smile">
    > "How has overall customer sentiment changed over the last 30 days?"
  </Card>
</CardGroup>

## More Example Questions

<Tabs>
  <Tab title="Recent Activity">
    > "Show me the 10 most recent customer calls"
  </Tab>

  <Tab title="Issue Investigation">
    > "Find all customer issues related to billing in the last 2 weeks"
  </Tab>

  <Tab title="Customer Deep Dive">
    > "Get all information about interactions with \[Customer Name]"
  </Tab>

  <Tab title="Sentiment Analysis">
    > "Show me all negative feedback from the last 7 days"
  </Tab>

  <Tab title="Feature Requests">
    > "List all feature requests grouped by product area"
  </Tab>

  <Tab title="Team Performance">
    > "Which team members have been mentioned positively by customers?"
  </Tab>
</Tabs>

## Security & Privacy

### Read-Only Access

<Check>
  * The MCP server provides **read-only** access to your data
  * No one can modify, delete, or create data through this connection
</Check>

### Authentication

<Info>
  * You sign in with your existing BuildBetter account — no separate credentials
  * **SSO-first**: work emails can be automatically routed to your identity provider
  * **Service account scope** available for non-interactive / shared automation use cases
  * Access is scoped to your organization's data only
  * No API keys to manage, rotate, or risk leaking
  * Config is stored server-side with encryption — not in browser local storage
  * Sessions can be revoked from your BuildBetter account settings
</Info>

### Network Security

<Info>
  * All connections use HTTPS encryption
  * No data is stored or cached by the MCP server
</Info>

### Best Practices

<Steps>
  <Step title="Review connected apps">
    Periodically check which AI clients have access in your account settings
  </Step>

  <Step title="Revoke unused sessions">
    Remove access for AI clients you no longer use
  </Step>

  <Step title="Report issues">
    Contact support if you suspect unauthorized access
  </Step>
</Steps>

## Limitations

<Tabs>
  <Tab title="Data Access">
    * **Read-only** — Cannot create, update, or delete data
    * **Organization-scoped** — Access limited to your organization's data
    * **No bulk exports** — Designed for targeted questions, not data dumps
  </Tab>

  <Tab title="Query Limits">
    * **Result size limits** — Very large result sets may be truncated
    * **Rate limiting** — Excessive requests may be throttled
  </Tab>

  <Tab title="What's Not Supported">
    * **No real-time updates** — Data reflects the latest snapshot, not a live stream
    * **No file access** — Cannot retrieve call recordings or attachments directly
  </Tab>
</Tabs>

## Troubleshooting

### Connection Issues

<AccordionGroup>
  <Accordion title="Connection refused or timeout errors">
    1. Check that you have internet connectivity
    2. Verify the URL is `https://mcp.buildbetter.app`
    3. Try restarting your AI client
  </Accordion>

  <Accordion title="Authentication errors">
    1. Ensure you're signing in with the correct BuildBetter account
    2. Try signing out and back in to refresh your session
    3. Check that your BuildBetter account is active
  </Accordion>
</AccordionGroup>

### Client Issues

<AccordionGroup>
  <Accordion title="MCP server not appearing in Claude Desktop">
    1. Open **Settings > Connectors** and verify the BuildBetter connector is listed
    2. Try removing and re-adding the connector
    3. Restart Claude Desktop completely
  </Accordion>

  <Accordion title="Sign-in popup not appearing">
    1. Check that your browser is not blocking popups
    2. Ensure your default browser is set correctly
    3. Try manually navigating to the sign-in URL if shown in logs
  </Accordion>
</AccordionGroup>

### Data Issues

<AccordionGroup>
  <Accordion title="No data returned">
    1. Verify you have data in your BuildBetter account
    2. Try broadening your question (e.g., remove date filters)
  </Accordion>

  <Accordion title="Unexpected results">
    1. Try rephrasing your question to be more specific
    2. Ask the assistant to clarify what data it found
  </Accordion>
</AccordionGroup>

## Support

<CardGroup cols={2}>
  <Card title="Account Settings" icon="gear" href="https://app.buildbetter.app/settings">
    Manage your account and connected apps
  </Card>

  <Card title="Contact Support" icon="life-ring" href="mailto:support@buildbetter.ai">
    Email [support@buildbetter.ai](mailto:support@buildbetter.ai) for help
  </Card>
</CardGroup>

***

<Note>
  Last updated May 2026
</Note>