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

# Data access

> Connect Copilots to your app data through an MCP Server

## How Copilots access your data

Gaia Copilot connects to your app's data through an **MCP Server** (Model Context Protocol). This gives the Copilot flexible access to read, update, and insert data. No endpoint configuration or function definitions needed.

<Info>
  The MCP Server is how Copilots interact with your app's live data. Without it, a Copilot can only chat and reference knowledge base documents. With MCP data access, it can answer questions like "Show me all deals closing this month" by querying your data directly.
</Info>

## How it works

<Steps>
  <Step title="Build your app with data models">
    Create your application with the data models and features you need.
  </Step>

  <Step title="Configure a Copilot">
    Describe the assistant you want and what data it should access.
  </Step>

  <Step title="Automatic connection">
    The MCP Server automatically connects your Copilot to your app's data. No manual configuration.
  </Step>

  <Step title="Optionally restrict with scopes">
    By default, the Copilot can access all your app's collections. Add scopes to restrict access when needed.
  </Step>
</Steps>

<Tip>
  Copilots can also access data synced from external sources via [datasets](/building/data-connectors). Add sources like HubSpot or Google Sheets to a dataset, sync the data, and the Copilot can query it alongside your app data.
</Tip>

## Query capabilities

A Copilot with MCP data access can run powerful queries across your data:

| Capability                  | Example question                             | What happens                                 |
| --------------------------- | -------------------------------------------- | -------------------------------------------- |
| **Filter**                  | "Show deals with status won"                 | Filters records by field value               |
| **Sort**                    | "Show deals sorted by amount, highest first" | Orders results by a field                    |
| **Search**                  | "Find contacts at Acme Corp"                 | Searches text fields                         |
| **Date ranges**             | "Deals closing this month"                   | Filters by date ranges                       |
| **Numeric ranges**          | "Deals over \$10,000"                        | Filters by numeric thresholds                |
| **Limits**                  | "Show the top 5 deals"                       | Limits result count                          |
| **Combined filters**        | "Open deals over \$10k closing this quarter" | Applies multiple filters at once             |
| **Aggregate**               | "What's the average deal size by status?"    | Groups and calculates sums, averages, counts |
| **Join across collections** | "Show deals with their contact details"      | Combines data from related collections       |
| **Insert**                  | "Add a new deal for Acme Corp"               | Creates new records                          |
| **Update**                  | "Mark that deal as won"                      | Modifies existing records                    |

## Scopes

By default, a Copilot can access **all collections** in your app. Use **scopes** to restrict it to specific collections when you want to limit what it can see.

### When to use scopes

* **Customer-facing Copilots.** Restrict to only the data relevant to the user's context.
* **Role-specific Copilots.** A sales Copilot only needs deals and contacts, not HR data.
* **Privacy-sensitive apps.** Limit access to prevent the Copilot from exposing sensitive data.

### Prompt examples

```text theme={null}
Give the Sales Coach access to only deals and contacts.
It shouldn't see employee or payroll data.
```

```text theme={null}
Restrict the support Copilot's data access to orders
and tickets only.
```

<Note>
  If you don't specify scopes, the Copilot can access all app collections. This is fine for most internal tools. Only add scopes when you need to restrict access.
</Note>

## Prompt examples

```text theme={null}
Give the Sales Coach Copilot access to deals and contacts
so it can look up pipeline data and find contact information.
```

```text theme={null}
Add data access to the support Copilot so it can look up
orders by order number and check order status.
```

```text theme={null}
Let the HR Copilot query employee records and
time-off requests.
```

<Warning>
  Your app must be built with data models before a Copilot can access data. The MCP Server connects to your existing collections. Build your app first, then configure the Copilot.
</Warning>

## Updating data access

You can update what data a Copilot can access through follow-up prompts:

### Expanding access

```text theme={null}
Give the Sales Coach access to the products data
so it can answer questions about pricing.
```

### Restricting access

```text theme={null}
Restrict the Sales Coach to only deals and contacts.
Remove access to everything else.
```

### Adding write capabilities

```text theme={null}
Let the support Copilot update order status
and add notes to customer records.
```

## Best practices

<AccordionGroup>
  <Accordion title="Start with read access">
    Begin by giving Copilots the ability to read and query data. Add write capabilities (inserting or updating records) only when needed.
  </Accordion>

  <Accordion title="Use scopes for customer-facing Copilots">
    Internal Copilots usually don't need scopes, they can access everything. For customer-facing Copilots, use scopes to restrict access to only the relevant collections.
  </Accordion>

  <Accordion title="Match data access to the Copilot's purpose">
    A sales Copilot needs deals and contacts. A support Copilot needs orders and tickets. Keep access relevant to what the Copilot does.
  </Accordion>

  <Accordion title="Combine with knowledge bases">
    Data access handles live data queries. Knowledge bases handle static reference material. Together, the Copilot can look up a customer's order *and* reference your return policy to answer a question.
  </Accordion>
</AccordionGroup>

## Copilot vs Agents data access

[Gaia Autopilot](/autopilot/overview) use a different model. Instead of a single MCP Server, agents call a fixed [tool registry](/autopilot/tools) (`query_collection`, `update_records`, `send_email`, `draft_for_approval`, and so on) with explicit risk tiers and an action log. Use the right one for the job:

* **Copilot reads and writes through MCP** for synchronous, user-driven questions.
* **Agents call typed tools** for asynchronous, autonomous work where every action is logged and high-risk steps go through draft-and-approve.

## Learn more

<CardGroup cols={2}>
  <Card title="Configuring a Copilot" icon="sliders" href="/copilots/configuring">
    Set up name, instructions, and behavior
  </Card>

  <Card title="Knowledge bases" icon="book" href="/copilots/knowledge">
    Add document references to your Copilot
  </Card>

  <Card title="Embedding" icon="message-bot" href="/copilots/embedding">
    Place the Copilot chat in your app
  </Card>

  <Card title="Data models" icon="database" href="/building/data-models">
    How app data is structured
  </Card>

  <Card title="Datasets" icon="plug" href="/building/data-connectors">
    Group external data sources and attach them to your app
  </Card>

  <Card title="Agent tools" icon="screwdriver-wrench" href="/autopilot/tools">
    How autonomous Agents access data and take action
  </Card>
</CardGroup>