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

# Connect MCP clients

> Learn how to connect MCP-supported AI tools (such as Claude Desktop, Claude Code, or Cursor) to your Squirrels project

Every Squirrels project has an MCP server running at `/mcp` automatically. Thus, AI tools that support the Model Context Protocol can be used to ask questions about the datasets configured in a Squirrels project.

This guide assumes that you have a Squirrels server running at `http://localhost:8000` in standalone mode.

## Authorization header (when required)

If your project uses `auth_type: required`, your MCP client must authenticate.

* For `auth_strategy: external`, MCP requests must include `Authorization: Bearer <token>` where `<token>` is a provider-issued OAuth access token (or JWT).
  * If authentication is missing/invalid, the server responds with HTTP 401 and a `WWW-Authenticate` header that includes a `resource_metadata` URL (usually served at `/.well-known/oauth-protected-resource`).
  * MCP clients that support OAuth discovery can use this to find the correct authorization server to authenticate with and fetch the access token from first.
* For `auth_strategy: managed`, MCP requests can include `x-api-key: <api_key>` as a header where `<api_key>` is an API key issued by the Squirrels API server.

## MCP clients

Choose which AI tool you want to use to interact with your Squirrels project.

<Tabs>
  <Tab title="Claude Desktop">
    **Prerequisites:**

    * [Claude Desktop](https://claude.com/download) installed
    * Node.js (>= v18.0.0) and npm: Download from [nodejs.org](https://nodejs.org/)
    * A [Claude.ai](https://claude.ai) account (the free plan works!)

    **Steps:**

    1. Open **Claude Desktop**.

    2. Click your name in the lower left corner, then click **Settings**.

    3. Click **Developer** under "Desktop app".

           <img src="https://mintcdn.com/squirrels/qAVA34a_gqQ5eURR/images/claude-desktop/settings-developer.png?fit=max&auto=format&n=qAVA34a_gqQ5eURR&q=85&s=6c9ec721a26b407313cb31605a43fabf" alt="Claude Desktop Settings" width="1303" height="793" data-path="images/claude-desktop/settings-developer.png" />

    4. Click the **Edit Config** button. This opens the file location of `claude_desktop_config.json`.

    5. Open `claude_desktop_config.json` in a text editor, and paste in the following:

    ```json theme={null}
    {
      "mcpServers": {
        "squirrels-analytics": {
          "command": "npx",
          "args": [
            "-y", "mcp-remote", 
            "http://localhost:8000/mcp"
          ]
        }
      }
    }
    ```

    6. **Save** the file and **exit Claude Desktop** (this is different than closing the window).

    * To exit Claude Desktop on Windows, click the menu icon on the top left corner and then click File -> Exit

    7. Open **Claude Desktop** again. You should now see the Squirrels project enabled by clicking the "search and tools" icon below the chat input.

           <img src="https://mintcdn.com/squirrels/qAVA34a_gqQ5eURR/images/claude-desktop/tools-menu.png?fit=max&auto=format&n=qAVA34a_gqQ5eURR&q=85&s=5233dc9d67cf8ef15dcca0da80423d3d" alt="Claude Desktop Tools Menu" width="861" height="531" data-path="images/claude-desktop/tools-menu.png" />

    8. Ask questions about the datasets in the Squirrels project. See the section below for example prompts.
  </Tab>

  <Tab title="Claude Code">
    **Prerequisites:**

    * [Claude Code](https://code.claude.com/docs/en/overview) (CLI) installed
    * Either:
      * A [Claude.ai](https://claude.ai/) account with Pro plan or higher, or
      * A [Claude Console](https://console.anthropic.com/) account with a credit balance

    **Steps:**

    1. Add the MCP server to Claude Code with name "squirrels-analytics" and URL `http://localhost:8000/mcp`.

    ```bash theme={null}
    claude mcp add --transport http squirrels-analytics http://localhost:8000/mcp
    ```

    2. Use the following commands to confirm details about the MCP server.

    ```bash theme={null}
    # List all configured servers
    claude mcp list

    # Get details about the MCP server you just added
    claude mcp get squirrels-analytics
    ```

    3. Start Claude Code by running `claude` in the terminal. You can check the server status by typing `/mcp` in the chat input.

    ```bash theme={null}
    # Start Claude Code
    claude

    # Check server status (within Claude Code)
    /mcp
    ```

    4. Ask questions about the datasets in the Squirrels project. See the section below for example prompts.
  </Tab>

  <Tab title="Cursor">
    **Prerequisites:**

    * [Cursor](https://cursor.com/download) (IDE) installed
    * A [Cursor](https://cursor.com/) account

    **Steps:**

    1. Open **Cursor**.

    2. Go to File -> Preferences -> **Cursor Settings**.

    3. Click on **Tools & MCP** in the left panel.

           <img src="https://mintcdn.com/squirrels/qAVA34a_gqQ5eURR/images/cursor/settings-mcp.png?fit=max&auto=format&n=qAVA34a_gqQ5eURR&q=85&s=af5847b4e7ce09297f360b9a88efaa20" alt="Cursor MCP Settings" width="1146" height="472" data-path="images/cursor/settings-mcp.png" />

    4. Click the **Add Custom MCP** button. This should open a `mcp.json` file.

    5. In the `mcp.json` file, paste the following and save.

    ```json theme={null}
    {
      "mcpServers": {
        "squirrels-analytics": {
          "url": "http://localhost:8000/mcp",
          "headers": {}
        }
      }
    }
    ```

    6. Press `Ctrl+I` to open the AI agent chat interface. Use `Ctrl+T` if you need to start a new chat.
    7. Ask questions about the datasets in the Squirrels project. See the section below for example prompts.
  </Tab>

  <Tab title="VS Code / GitHub Copilot">
    **Prerequisites:**

    * [VS Code](https://code.visualstudio.com/) (IDE) installed
    * VS Code extensions: [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) and [GitHub Copilot Chat](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot-chat) installed
    * A [GitHub](https://github.com/) account

    **Steps:**

    1. Open **VS Code**.
    2. Create a `.vscode` folder in your project's root directory if it doesn't exist.
    3. Create and open the `mcp.json` file in the `.vscode` folder.
    4. In the `mcp.json` file, paste the following and save.

    ```json theme={null}
    {
      "servers": {
        "squirrels-analytics": {
          "url": "http://localhost:8000/mcp",
          "headers": {}
        }
      }
    }
    ```

    5. Click **Start** on the MCP server.
    6. Press `Ctrl+Shift+I` to open the AI agent chat interface. Use `Ctrl+N` if you need to start a new chat.
    7. Ask questions about the datasets in the Squirrels project. See the section below for example prompts.
  </Tab>
</Tabs>

## Example prompts

The following are sample prompts that can be used for any Squirrels project when interacting with an AI chat agent:

```text wrap theme={null}
What datasets do you have access to?
```

```text wrap theme={null}
What tools do you have access to?
```

Other prompts to ask depend on the datasets in your Squirrels project.