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

# Claude MCP Server

> Ask your data anything — get trusted AI answers directly inside Claude.

## Overview

The Upsolve AI MCP server connects Claude to your data warehouse, turning plain-English questions into SQL queries, charts, and AI-generated insights — all rendered as an interactive panel inside your Claude conversation.

Unlike generic text-to-SQL tools, Upsolve brings your team's **institutional knowledge** into every answer: your KPI definitions, validated SQL patterns, business logic rules, and behavioral guardrails are all encoded into the agent before it ever sees a question. The result is answers you can trust, not just answers that look right.

**Server URL:** `https://mcp.upsolve.ai/mcp`
**Transport:** Streamable HTTP
**Auth:** OAuth 2.0

<Note>
  The Upsolve MCP server is **read-only**. It never writes, modifies, or deletes
  data in your connected data sources.
</Note>

***

## What You Get

When Claude calls the Upsolve MCP, results are returned as an **interactive panel** rendered directly in the conversation — no tab switching, no copy-pasting SQL. Each response includes:

| Component       | Description                                             |
| --------------- | ------------------------------------------------------- |
| **AI insights** | Plain-English summary of key findings                   |
| **Charts**      | Auto-generated bar, line, pie, and other visualizations |
| **Data table**  | Sortable results with CSV export                        |

Multi-turn follow-ups are supported — Claude maintains conversation context across questions in the same thread.

***

## Prerequisites

Before connecting, make sure you have:

1. An active **Upsolve AI account** — [start a free trial at upsolve.ai](https://upsolve.ai) (no credit card required)
2. At least one **data source connected** in Upsolve (Snowflake, BigQuery, Amazon Redshift, PostgreSQL, or any JDBC/ODBC-compatible warehouse)
3. **Claude.ai** or **Claude Desktop** — either works

<Tip>
  If you haven't connected a data source yet, go to your Upsolve workspace →
  **Connect** tab → choose your warehouse. A sample database is available if you
  want to test before connecting your own data.
</Tip>

***

## Connecting to Claude

<Tabs>
  <Tab title="Claude.ai (web)">
    <Steps>
      <Step title="Open Connectors settings">
        Go to [claude.ai](https://claude.ai) → click your profile icon → **Settings** → **Connectors**.
      </Step>

      <Step title="Add a custom connector">
        Click **Add custom connector** (or search for Upsolve if it appears in the directory).
      </Step>

      <Step title="Enter the server URL">
        Paste the server URL:

        ```
        https://mcp.upsolve.ai/mcp
        ```
      </Step>

      <Step title="Sign in with Upsolve">
        Claude will redirect you to Upsolve's OAuth sign-in. Log in with your Upsolve account credentials. You'll be redirected back to Claude once authorized.
      </Step>

      <Step title="Enable in your conversation">
        Open a new Claude conversation. Toggle the Upsolve connector on in the toolbar. You're ready to ask your first question.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Claude Desktop">
    <Steps>
      <Step title="Open Connector settings">
        Open Claude Desktop → **Settings** → **Connectors** → **Add custom connector**.
      </Step>

      <Step title="Enter the server URL">
        Paste the server URL:

        ```
        https://mcp.upsolve.ai/mcp
        ```
      </Step>

      <Step title="Sign in with Upsolve">
        A browser window will open prompting you to sign in to your Upsolve account via OAuth. Complete sign-in and return to Claude Desktop.
      </Step>

      <Step title="Start asking questions">
        Open a new conversation. The Upsolve connector is active automatically.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Claude Code">
    Add the following to your MCP configuration file:

    ```json theme={null}
    {
      "mcpServers": {
        "upsolve": {
          "url": "https://mcp.upsolve.ai/mcp",
          "transport": "streamable-http"
        }
      }
    }
    ```

    Run `claude mcp add` or update your `.mcp.json` directly. Authenticate via OAuth when prompted.
  </Tab>
</Tabs>

***

## Authentication

Upsolve MCP uses **OAuth 2.0**. When you connect for the first time, Claude redirects you to sign in to your Upsolve account. Your Upsolve credentials are never shared with Claude or Anthropic — only a short-lived OAuth access token is passed to authorize requests.

* Tokens are scoped to your Upsolve account and the data sources you have access to
* Revoking access is instant: go to your Upsolve account → **Settings** → **Connected Apps** and remove Claude

***

## Available Tools

### `analyze_data`

The core tool. Ask any analytical question in plain English — Upsolve's agent generates and executes SQL against your connected data source and returns results as an interactive panel inside Claude.

**Inputs:**

| Parameter   | Type   | Required | Description                                     |
| ----------- | ------ | -------- | ----------------------------------------------- |
| `message`   | string | Yes      | Your question or data request in plain English  |
| `thread_id` | string | No       | Thread ID to continue a multi-turn conversation |

**Returns:** An interactive MCP App panel with AI insights, charts, and a sortable data table.

**Annotations:** `readOnlyHint: true` — this tool only reads data, never writes or modifies anything.

<Note>
  Claude manages `thread_id` automatically in multi-turn conversations — you
  don't need to set it manually. Just keep asking follow-up questions in the
  same chat thread.
</Note>

***

## Example Prompts

### Explore and summarize databases and datasets

These prompts help you understand what data is available and get high-level summaries before diving into specifics.

```
What tables are in my connected data source, and what does each one contain?
```

```
Summarize the key metrics in my sales dataset for last quarter.
```

```
What are the top-level trends in my data over the past 12 months?
```

```
Show me a breakdown of records by status across all order tables.
```

### Generate and execute data logic for visualization

These prompts produce charts and visual outputs — Upsolve generates the SQL, runs it, and renders the chart inline.

```
Create a bar chart showing monthly revenue by product category for the last 6 months.
```

```
Show me a trend line of daily active users over the past 30 days.
```

```
Build a visualization comparing conversion rates across our marketing channels this quarter.
```

```
Plot customer acquisition by region as a stacked area chart, month by month.
```

### Generate data insights from analytics

These prompts ask Upsolve to interpret results and surface what matters — not just data, but the "so what."

```
What are the key takeaways from our Q3 sales performance?
```

```
Which customer segments are showing the highest churn risk this month?
```

```
Identify any anomalies or outliers in this week's transaction data.
```

```
Why did revenue drop in October? Walk me through the most likely causes.
```

***

## Multi-turn Conversations

Upsolve supports **multi-turn analytical conversations** — you can refine, drill down, and pivot across follow-up questions without losing context.

Claude manages conversation continuity automatically via `thread_id`. You don't need to repeat context between questions in the same conversation thread.

**Example conversation:**

> **You:** Show me revenue for Q3 broken down by product line.
> *(Upsolve returns a chart and table)*
>
> **You:** Now filter to just enterprise customers.
> *(Upsolve refines the same query with the new filter)*
>
> **You:** Which product line had the highest month-over-month growth?
> *(Upsolve adds a growth calculation to the existing analysis)*

***

## How Upsolve Produces Reliable Answers

Generic text-to-SQL tools connect to your schema — and that's it. Answers look right in a demo and fail in production because they have no context for how your business actually works.

Upsolve encodes **six layers of institutional context** into the agent before it answers any question:

| Layer                      | What it encodes                                               |
| -------------------------- | ------------------------------------------------------------- |
| **Data model & schema**    | Tables, columns, and relationships                            |
| **KPI definitions**        | Both the technical SQL and the plain-English business meaning |
| **Validated SQL patterns** | Your team's known-good queries for common questions           |
| **Business rules**         | Edge cases, filters, and logic specific to your data          |
| **Behavioral guardrails**  | What the agent should and should not answer                   |
| **Column descriptions**    | Business-language labels for technical column names           |

This is what makes the difference between an agent that hallucinates in front of the CFO and one your team actually relies on.

<Tip>
  To add or update context for your agent, go to your Upsolve workspace →
  **Agent Studio** → select your agent → open the relevant context tab. Changes
  take effect on the next query.
</Tip>

***

## Security & Data Handling

* **Read-only access** — the `analyze_data` tool carries `readOnlyHint: true`. It queries your data; it never modifies it.
* **Data scoping** — the agent only has access to the data sources connected in your Upsolve account. It cannot query data outside that scope.
* **No data retention** — queries execute in real-time. Upsolve does not store your query results or conversation content beyond the session.
* **Encrypted in transit** — all data transmitted between Claude, Upsolve's MCP server, and your data source is encrypted via HTTPS/TLS.
* **Your credentials stay with you** — your data warehouse credentials are stored in Upsolve, not passed to Claude or Anthropic.

For full details, see the [Upsolve Privacy Policy](https://upsolve.ai/privacy).

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Claude says it can't find the Upsolve connector">
    Make sure the connector is toggled **on** for your current conversation — look for the Upsolve icon in the conversation toolbar. If it doesn't appear, go to **Settings → Connectors** and confirm the server URL is `https://mcp.upsolve.ai/mcp`.
  </Accordion>

  <Accordion title="Authentication failed or OAuth loop">
    Try disconnecting and reconnecting the integration:

    1. Go to **Settings → Connectors** in Claude
    2. Remove the Upsolve connector
    3. Re-add it with the server URL `https://mcp.upsolve.ai/mcp`
    4. Complete the OAuth sign-in flow again

    If the issue persists, check that your Upsolve account is active at [upsolve.ai](https://upsolve.ai) and that you're signing in with the correct credentials.
  </Accordion>

  <Accordion title="Upsolve returns an error about no data source connected">
    The agent needs at least one connected data source to answer questions. Go to your Upsolve workspace → **Connect** tab → connect a data warehouse. If you want to test without your own data, use the sample database available in the Connect tab.
  </Accordion>

  <Accordion title="Answers look wrong or don't match what I expect">
    This usually means the agent is missing context about your specific data or business logic. In your Upsolve workspace, go to **Agent Studio** → select your agent and review:

    * **KPI definitions** — are your key metrics defined with both SQL and business-language descriptions?
    * **Golden assets** — have you added validated SQL patterns for common questions?
    * **Business rules** — are there edge cases or filters that should always apply?

    The more context you encode, the more reliable the answers become.
  </Accordion>

  <Accordion title="The interactive panel isn't rendering in Claude">
    The interactive chart and table panel requires **Claude.ai (web)** or **Claude Desktop** with MCP App support enabled. Claude Code displays results as structured text instead of an interactive panel — all data is still returned, just without the visual UI.
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Connect a Data Source" icon="database" href="/embedded-bi/data-connection/data-connection">
    Link your Snowflake, BigQuery, Redshift, or PostgreSQL warehouse to Upsolve.
  </Card>

  <Card title="Build Your Agent" icon="robot" href="/ai-agent-builder/agents">
    Set up KPI definitions, golden assets, and behavioral guardrails in Agent Studio.
  </Card>

  <Card title="Test Before You Ship" icon="flask" href="/ai-agent-builder/agents#creating-evaluations">
    Run your agent against a golden query set before exposing it to business users.
  </Card>

  <Card title="Deploy to Other Surfaces" icon="share-nodes" href="/ai-agent-builder/applications">
    Embed your analytics agent in your product, Slack, or other MCP-compatible tools.
  </Card>
</CardGroup>

***

## Support

* **Email:** [support@upsolve.ai](mailto:support@upsolve.ai)
* **Website:** [upsolve.ai](https://upsolve.ai)
* **Privacy Policy:** [upsolve.ai/privacy](https://upsolve.ai/privacy)