# Install Sphinx MCP in ChatGPT Desktop
Source: https://docs.sphinx.ai/chatgpt-desktop/install-sphinx-mcp

Connect ChatGPT Desktop to the Sphinx MCP server and authorize access to your workspace.

Connect ChatGPT Desktop to Sphinx so you can use Sphinx tools in your chats.

## Prerequisites

Before you begin, make sure you have:

* The latest version of ChatGPT Desktop
* A Sphinx account with access to a workspace

## Add the Sphinx MCP server

<Steps>
  <Step title="Open Settings">
    In ChatGPT Desktop, open the account menu in the bottom-left corner and click **Settings**.

    <Frame>
      <img alt="ChatGPT Desktop account menu with the Settings option highlighted" />
    </Frame>
  </Step>

  <Step title="Open Plugins">
    In the Settings sidebar, click **Plugins**.

    <Frame>
      <img alt="ChatGPT Desktop Settings with Plugins highlighted in the sidebar" />
    </Frame>
  </Step>

  <Step title="Add an MCP server">
    Click **Add**, then select **Add MCP server**.

    <Frame>
      <img alt="ChatGPT Desktop Plugins page with Add MCP server selected in the Add menu" />
    </Frame>
  </Step>

  <Step title="Configure the Sphinx MCP server">
    Complete the form with the following values:

    | Field | Value |
    | - | - |
    | **Name** | `sphinx` |
    | **Type** | **Streamable HTTP** |
    | **URL** | `https://api.prod.sphinx.ai/mcp` |

    Leave the remaining fields blank, then click **Save**.

    <Frame>
      <img alt="Custom MCP server form configured with the Sphinx name, Streamable HTTP type, and Sphinx MCP URL" />
    </Frame>
  </Step>

  <Step title="Authenticate with Sphinx">
    Open the **MCPs** tab on the Plugins page, find **sphinx**, and click **Authenticate**. ChatGPT opens the Sphinx authorization page in your browser.

    <Frame>
      <img alt="MCPs tab on the ChatGPT Desktop Plugins page showing the Authenticate button for sphinx" />
    </Frame>
  </Step>

  <Step title="Allow access to your workspace">
    On the authorization page, select the Sphinx workspace you want to connect, then click **Allow access**.

    <Frame>
      <img alt="Sphinx authorization page with a workspace selector and Allow access button" />
    </Frame>
  </Step>
</Steps>

<Check>
  The Sphinx MCP server is now connected and ready to use in ChatGPT Desktop.
</Check>


# Setup ChatGPT Desktop LLM Gateway
Source: https://docs.sphinx.ai/chatgpt-desktop/setup-llm-gateway

Install ChatGPT for Windows and connect it to the Sphinx LLM Gateway.

Connect the ChatGPT desktop app for Windows to the Sphinx LLM Gateway.

## Prerequisites

Before you begin, make sure you have:

* A Windows computer
* Your Sphinx API token
* Permission to install applications and approve a Windows User Account Control prompt

## Install the Sphinx LLM Gateway

<Steps>
  <Step title="Download ChatGPT for Windows">
    Go to [chatgpt.com/download](https://chatgpt.com/download/) and download the ChatGPT desktop app for Windows.
  </Step>

  <Step title="Download the Sphinx LLM Gateway installer">
    Open the [Sphinx LLM Gateway installer in Google Drive](https://drive.google.com/file/d/1Ru-qEO6kxqLNc1QZMBoijGhtiaZES536/view?usp=sharing), then click **Download**.
  </Step>

  <Step title="Run the gateway installer">
    Open your downloads and double-click the downloaded `.exe` file.
  </Step>

  <Step title="Allow the installer to run">
    If Microsoft Defender SmartScreen displays **Windows protected your PC**, click **More info**.

    <Frame>
      <img alt="Windows protected your PC warning showing the More info link" />
    </Frame>

    Confirm that the app is **Codex Sphinx LLM Gateway Setup.exe**, then click **Run anyway**.

    <Frame>
      <img alt="Windows protected your PC warning showing Codex Sphinx LLM Gateway Setup.exe and the Run anyway button" />
    </Frame>

    <Warning>
      Windows may list the publisher as unknown. Continue only if you downloaded the installer from the Google Drive link above.
    </Warning>
  </Step>

  <Step title="Complete the setup wizard">
    On the welcome screen, click **Next**.

    <Frame>
      <img alt="Welcome screen for the Codex Sphinx LLM Gateway setup wizard" />
    </Frame>

    Enter your Sphinx API token, then click **Next**.

    <Frame>
      <img alt="Codex Sphinx LLM Gateway setup wizard with a field for the Sphinx API token" />
    </Frame>

    When the installer is ready, click **Install**.

    <Frame>
      <img alt="Codex Sphinx LLM Gateway setup wizard showing the Install button" />
    </Frame>

    After the installation completes, click **Finish**.

    <Frame>
      <img alt="Successful Codex Sphinx LLM Gateway installation with the Finish button" />
    </Frame>

    <Warning>
      Keep your API token private. Do not share it or include it in screenshots.
    </Warning>
  </Step>

  <Step title="Start ChatGPT">
    Launch the ChatGPT desktop app and complete the introductory prompts.
  </Step>

  <Step title="Finish Windows setup">
    When ChatGPT asks for one-time permission to work on your computer, click **Finish setup**. In the Windows User Account Control prompt, click **Yes**.

    <Frame>
      <img alt="ChatGPT Finish Windows setup screen with a User Account Control prompt and instructions to click Yes" />
    </Frame>
  </Step>
</Steps>

## Verify the connection

After setup, ChatGPT opens to the main chat page. Confirm that **Sphinx Gateway** appears in the bottom-left corner.

<Frame>
  <img alt="ChatGPT main chat page showing Sphinx Gateway in the bottom-left corner" />
</Frame>

<Check>
  You can now start a chat using the Sphinx LLM Gateway.
</Check>


# API key setup for Claude Code CLI
Source: https://docs.sphinx.ai/claude-code-cli/api-key-setup

Create a Sphinx API key and configure the Sphinx MCP server in Claude Code CLI.

## Video tutorial

<Frame>
  <iframe title="User Setup for Claude Code CLI" />
</Frame>

## Set up your API key

<Steps>
  <Step title="Disable the plugin">
    Disable the Sphinx plugin before configuring the MCP server.
  </Step>

  <Step title="Open Sphinx settings">
    Navigate to [app.sphinx.ai](https://app.sphinx.ai). In the top-left corner, click the settings gear.
  </Step>

  <Step title="Open API Keys">
    From the dropdown menu, select **API Keys**.
  </Step>

  <Step title="Create an API key">
    Click **New Key**, give the key a name, set its expiration, and click **Create**.
  </Step>

  <Step title="Copy the API key">
    Copy the generated API key.
  </Step>

  <Step title="Configure the Sphinx MCP server">
    Navigate to the unzipped `sphinx.zip` folder and open `.mcp.json`.

    Add a `headers` section to the Sphinx MCP server configuration. Replace `<api key>` with the API key you copied:

    ```json .mcp.json theme={null}
    {
      "mcpServers": {
        "sphinx": {
          "type": "http",
          "url": "https://api.prod.sphinx.ai/mcp",
          "headers": {
            "Authorization": "Bearer <api key>"
          }
        }
      }
    }
    ```
  </Step>
</Steps>


# Connect Claude Desktop to an API gateway
Source: https://docs.sphinx.ai/claude-desktop/api-gateway-setup

Configure Claude Desktop to send requests through the Sphinx API gateway.

Use Claude Desktop's third-party inference settings to route requests through the Sphinx API gateway.

## Video Tutorial

<iframe title="Connecting Claude Desktop to the Sphinx API Gateway" />

## Prerequisites

Before you begin, make sure you have:

* The latest version of [Claude Desktop](https://claude.com/download)
* Access to Claude Desktop
* Your organization is enabled for the Sphinx LLM Gateway
* Your Sphinx API key

## Configure the API gateway

<Steps>
  <Step title="Open Claude Desktop">
    Launch Claude Desktop and sign in with your company email. <Note>Claude requires you to sign in at least once with an email or enterprise SSO. This account will NOT be used after this process is complete. You will instead be using Sphinx's private backend, which maintains stricter security standards.</Note>
  </Step>

  <Step title="Enable Developer Mode">
    From the application menu, select **Help → Troubleshooting → Enable Developer Mode**.

    <Accordion title="Windows users">
      On Windows, the **Help** menu is located in the top-left corner of the Claude Desktop window. Click the menu button, then select **Help → Troubleshooting → Enable Developer Mode**.

      <Frame>
        <img alt="Claude Desktop for Windows with the top-left menu open, showing Help, Troubleshooting, and Enable Developer Mode" />
      </Frame>
    </Accordion>

    Confirm the warning when prompted. Claude Desktop restarts and adds a **Developer** menu to the application menu bar.

    <Note>
      If the **Developer** menu is already visible, Developer Mode is enabled and you can continue to the next step.
    </Note>
  </Step>

  <Step title="Open the third-party inference settings">
    Select **Developer → Configure Third-Party Inference**.
  </Step>

  <Step title="Choose Gateway">
    In the configuration dialog, select **Gateway**.
  </Step>

  <Step title="Enter the gateway credentials">
    Complete the form with the following values:

    | Field | Value |
    | - | - |
    | **Credential Kind** | **Static API Key** |
    | **Gateway Base URL** | `https://api.prod.sphinx.ai/ai-gateway/anthropic` |
    | **API Key** | Your Sphinx API key |
    | **Gateway Auth Scheme** | **Bearer** |

    Enter the gateway base URL exactly as shown.
  </Step>

  <Step title="Test the connection">
    Click **Test Connection**.

    Continue only after Claude Desktop confirms that the connection was successful.
  </Step>

  <Step title="Restart with the gateway">
    Restart Claude Desktop. When prompted to choose how to continue, select **Continue with Gateway**.
    <Note>After you log in with the gateway, your Claude Desktop application will no longer send data directly to Anthropic. All AI usage will instead go through Sphinx's secure API gateway.</Note>
  </Step>
</Steps>

## Additional steps for Windows users

<Warning>
  This section applies only to Windows users. If you are using macOS, skip to [Verify Claude Desktop](#verify-claude-desktop).
</Warning>

To use Cowork with the Sphinx LLM Gateway on Windows, complete these steps after restarting Claude Desktop with the gateway:

<Steps>
  <Step title="Open Claude Desktop">
    Launch Claude Desktop after it restarts with the gateway.
  </Step>

  <Step title="Open Cowork">
    Click **Cowork** in the top-left panel.
  </Step>

  <Step title="Install the virtualization software">
    When Claude Desktop reports that the Virtual Machine Platform is not available, click **Enable** to install the required Windows virtualization software.

    <Frame>
      <img alt="Claude Desktop on Windows showing a Virtual Machine Platform not available message with an Enable button" />
    </Frame>
  </Step>

  <Step title="Restart your computer">
    After the virtualization software is installed, click **Restart now** to restart your computer and finish the setup.

    <Frame>
      <img alt="Claude Desktop on Windows prompting the user to restart the computer to finish Virtual Machine Platform setup" />
    </Frame>
  </Step>

  <Step title="Use Cowork with Sphinx">
    After your computer restarts, open Claude Desktop and select **Cowork**. You can now use Cowork with the Sphinx LLM Gateway.
  </Step>
</Steps>

## Verify Claude Desktop Is Connected

Start a new chat and send a simple prompt, such as:

```text theme={null}
Reply with: Gateway connection successful.
```

If Claude responds, Claude Desktop can reach AI models through the gateway.


# Connect Claude Desktop to Sphinx MCP when using Third-Party Inference
Source: https://docs.sphinx.ai/claude-desktop/sphinx-mcp/install-sphinx-mcp

Connect Claude Desktop to the Sphinx MCP server when you use the Sphinx LLM Gateway.

## Prerequisites

Before you begin, make sure you have:

* Connected Claude Desktop to the [Sphinx LLM Gateway](../api-gateway-setup)
* Access to a Sphinx workspace

## Add the Sphinx MCP server

<Steps>
  <Step title="Open the third-party inference settings">
    In Claude Desktop, select **Developer → Configure Third-Party Inference**.

    <Frame>
      <img alt="Claude Desktop Developer menu with Configure Third-Party Inference highlighted" />
    </Frame>
  </Step>

  <Step title="Open Connectors">
    In the configuration sidebar, click **Connectors**.

    <Frame>
      <img alt="Claude Desktop third-party inference settings with Connectors selected in the sidebar" />
    </Frame>
  </Step>

  <Step title="Add a blank server">
    Click **Add server**, then select **Blank**.

    <Frame>
      <img alt="Claude Desktop Connectors page with Blank selected from the Add server menu" />
    </Frame>
  </Step>

  <Step title="Configure the Sphinx MCP server">
    Complete the form with the following values:

    | Field | Value |
    | - | - |
    | **Name** | `sphinx` |
    | **Transport** | **Streamable HTTP** |
    | **URL** | `https://api.prod.sphinx.ai/mcp` |
    | **OAuth** | **Auto-register (dynamic client registration)** |

    Click **Sign in & test**. Claude Desktop opens the Sphinx authorization page in your browser.

    <Frame>
      <img alt="Sphinx MCP server configured with Streamable HTTP transport and automatic OAuth registration" />
    </Frame>
  </Step>

  <Step title="Allow access to your workspace">
    On the authorization page, select the Sphinx workspace you want to connect, then click **Allow access**.

    <Frame>
      <img alt="Sphinx authorization page with a workspace selector and Allow access button" />
    </Frame>

    Return to Claude Desktop and click **Apply Changes**. Claude Desktop restarts to apply the configuration.
  </Step>

  <Step title="Confirm the connection and apply changes">
    After Claude Desktop restarts, return to **Developer → Configure Third-Party Inference → Connectors**. Under the Sphinx server, confirm that Claude Desktop displays **Connected successfully**, then click **Apply Changes**.

    <Frame>
      <img alt="Sphinx MCP server status showing Connected successfully and a list of exposed tools" />
    </Frame>
  </Step>

  <Step title="Restart Claude Desktop">
    Fully quit Claude Desktop, then reopen it before using the Sphinx connectors.
  </Step>

  <Step title="Use Sphinx connectors">
    Start a new chat and click **+ → Connectors**. **Sphinx** now appears in the connectors list and is ready to use.

    <Frame>
      <img alt="Claude Desktop chat composer with Sphinx enabled in the Connectors menu" />
    </Frame>
  </Step>
</Steps>

<Check>
  Claude Desktop is connected to Sphinx MCP, and Sphinx connectors are available in your chats.
</Check>


# Sphinx plugin onboarding for Claude
Source: https://docs.sphinx.ai/claude/sphinx-plugin-onboarding

Install and connect the Sphinx plugin in Claude.ai, Claude Desktop, and Claude Code CLI.

Use this guide to make the Sphinx plugin available to your organization and connect it to Claude.ai, Claude Desktop, or Claude Code CLI.

<Note>
  Claude.ai, Claude Desktop, and Claude Code use similar interfaces, but their setup steps differ. Organization administrators should complete the organization setup first. Each user must then connect and authenticate Sphinx.
</Note>

## Organization administrator setup

After you complete this setup, members of your organization can access the Sphinx plugin and connector according to the access level you select. Each member must authenticate the Sphinx connector before using it.

### Prerequisites

Before you begin, make sure you have:

* Organization administrator access in Claude
* The `sphinx.zip` plugin file from Sphinx
* The Sphinx custom connector details

### Upload the Sphinx plugin

<Steps>
  <Step title="Open organization settings">
    Sign in to [Claude.ai](https://claude.ai), click your user icon in the bottom-left corner, and select **Organization settings**.
  </Step>

  <Step title="Open the Plugins page">
    Navigate to **Plugins**, then click **Add plugins** and select **Upload from file**.
  </Step>

  <Step title="Upload the plugin">
    Enter `Sphinx` as the marketplace name. Click the file icon, select `sphinx.zip`, and upload it.
  </Step>

  <Step title="Add the Sphinx connector">
    Add Sphinx as a custom connector using the connector details provided by Sphinx.
  </Step>

  <Step title="Set user access">
    Choose the access level for the Sphinx plugin:

    | Access level | Behavior |
    | - | - |
    | **Available to install** | Users can choose whether to install the plugin. |
    | **Installed by default** | The plugin is installed for users by default. |
    | **Not available** | The plugin is hidden from users but remains visible to administrators. |
    | **Required** | The plugin is always installed and users cannot uninstall it. |
  </Step>
</Steps>

<Info>
  The plugin becomes available in Claude.ai and Claude Desktop. Claude Code users working from the CLI must install the plugin manually. The connector is available in Claude.ai, Claude Desktop, and Claude Code, but users must authenticate it themselves for full functionality.
</Info>

## Connect Claude.ai or Claude Desktop

Complete these steps after your organization administrator has made the Sphinx plugin and connector available.

### Prerequisites

Before you begin, make sure you have:

* Access to an organization where the Sphinx plugin is available
* Access to a Sphinx workspace

<Steps>
  <Step title="Open settings">
    Click your user icon in the bottom-left corner, then select **Settings**.
  </Step>

  <Step title="Open Connectors">
    Navigate to **Connectors**.
  </Step>

  <Step title="Connect Sphinx">
    Find Sphinx and click **Connect**.
  </Step>

  <Step title="Authorize your workspace">
    Select the Sphinx workspace you want to use, then click **Connect**.
  </Step>
</Steps>

<Check>
  Sphinx is connected and available in Claude.ai or Claude Desktop.
</Check>

## Allow artifact uploads in Claude.ai

Add the Sphinx domain to Claude.ai so artifacts can upload files to Sphinx.

<Steps>
  <Step title="Open settings">
    Click your user icon in the bottom-left corner, then select **Settings**.
  </Step>

  <Step title="Open Capabilities">
    Navigate to **Capabilities** and scroll to the bottom of the page.
  </Step>

  <Step title="Allow the Sphinx domain">
    Under **Additional allowed domains**, add `*.sphinx.ai`.
  </Step>
</Steps>

## Install the plugin in Claude Code CLI

<Warning>
  Claude Code loads the plugin from the unzipped `sphinx.zip` folder. If you delete that folder, the Sphinx plugin will disappear from Claude Code. Keep the folder in a permanent location.
</Warning>

### Prerequisites

Before you begin, make sure you have:

* Claude Code installed
* The `sphinx.zip` plugin file from Sphinx
* Access to a Sphinx workspace

<Steps>
  <Step title="Extract the plugin">
    Download `sphinx.zip` and unzip it to a local folder.
  </Step>

  <Step title="Add the marketplace">
    In Claude Code, run `/plugin`. Navigate to **Marketplaces**, select **Add Marketplace**, paste the path to the unzipped plugin folder, and press **Enter**.
  </Step>

  <Step title="Install the Sphinx plugin">
    Open the **Discover** tab and install the Sphinx plugin.
  </Step>

  <Step title="Reload the plugin">
    Run `/reload-plugin`.
  </Step>

  <Step title="Open MCP settings">
    Run `/mcp`, then select the `Plugin:sphinx:sphinx` MCP server.

    <Note>
      If you already connected Sphinx in Claude.ai or Claude Desktop, you might see another Sphinx MCP server. Select the server named `Plugin:sphinx:sphinx` for the plugin installed from the local marketplace.
    </Note>
  </Step>

  <Step title="Authenticate Sphinx">
    Enable the MCP server and complete the authentication flow.
  </Step>
</Steps>

<Check>
  The Sphinx plugin and MCP server are enabled in Claude Code CLI.
</Check>

## Use an API key with Claude Code CLI

If you prefer API-key authentication, first complete the Claude Code CLI installation above. Then follow [API key setup for Claude Code CLI](../claude-code-cli/api-key-setup) to create a Sphinx API key and add it to `.mcp.json`.

<Warning>
  Treat your Sphinx API key as a secret. Do not commit `.mcp.json` if it contains the key, and do not share the key in logs or messages.
</Warning>


# Connect GitHub and add a repository
Source: https://docs.sphinx.ai/git-ingest

A step-by-step guide to connecting GitHub and adding repository knowledge to Sphinx.

Connect your GitHub account, choose a repository, and tell Sphinx what to learn from it. A **repository** is a collection of files stored in GitHub. An **ingest** is the process of reading those files and turning them into knowledge in Sphinx.

## Before you start

Have these ready:

* Your Sphinx sign-in and the workspace you want to use.
* Your GitHub sign-in and the name of the repository you want to add.
* Someone who manages your company's GitHub account, in case GitHub asks for their approval.

<Note>
  Git ingest is currently in **beta**. If you cannot find **Git Repository** in Sphinx, ask the Sphinx team to enable it for your workspace.
</Note>

The screenshots use development workspaces and `sphinx-ml/docs` as an example repository. Your workspace and connector names may look different.

## 1. Connect GitHub

A **connector** is the saved connection between Sphinx and GitHub. You will create one, allow access in GitHub, and then sign in to it.

<Steps>
  <Step title="Open Connectors">
    In Sphinx, click **Settings** at the bottom left.

    Check that the correct **Workspace** is selected, then click **Connectors**.

    <Frame>
      <img alt="Sphinx Settings drawer with a workspace selected and the Connectors link visible" />
    </Frame>
  </Step>

  <Step title="Choose GitHub">
    Click **New connector**.

    Under **Documents & repositories**, click **GitHub**.

    <Frame>
      <img alt="GitHub card under Documents and repositories on the Available connectors page" />
    </Frame>
  </Step>

  <Step title="Name your connection">
    In **Connector name**, enter a name you will recognize, such as `GitHub documentation demo`.

    Click **Connect GitHub**. GitHub opens in another tab. Keep the Sphinx tab open.

    <Frame>
      <img alt="GitHub connector form with an example name and the Connect GitHub button" />
    </Frame>
  </Step>

  <Step title="Choose the repository in GitHub">
    Sign in to GitHub if asked. Choose the account or company that owns your repository.

    Select **Only select repositories**, open **Select repositories**, and choose the repository you want Sphinx to read. Our example is `sphinx-ml/docs`.

    Review the permissions, then click **Install**. If the app is already installed, you may see **Update access** instead.

    <Frame>
      <img alt="GitHub repository access screen with sphinx-ml/docs selected and read access to code and metadata shown" />
    </Frame>

    <Note>
      If GitHub shows **Request** or says an organization owner must complete this action, ask the person who manages your company's GitHub account to finish this step. See [GitHub's installation help](https://docs.github.com/en/apps/using-github-apps/installing-a-github-app-from-a-third-party) for details.
    </Note>
  </Step>

  <Step title="Return to Sphinx and sign in with GitHub">
    Return to your Sphinx connector tab. Refresh the page if needed.

    Under **Authentication**, click **Sign in with GitHub**. Follow GitHub's prompts to authorize the connection.

    When you see **Authentication successful. You can close this tab.**, close that tab and return to Sphinx.

    <Tip>
      If **Sign in with GitHub** is greyed out, finish **Install GitHub App** first. Installation and sign-in are two separate steps.
    </Tip>
  </Step>

  <Step title="Check that you are connected">
    Your connector should now show **Manage GitHub App** and **Reconnect GitHub**. Refresh the page if those buttons have not updated.

    You are ready to set up the ingest.

    <Frame>
      <div aria-label="Connected GitHub authentication panel showing Manage GitHub App and Reconnect GitHub" />
    </Frame>
  </Step>
</Steps>

## 2. Set up the ingest

<Steps>
  <Step title="Start a new ingest">
    In the same Sphinx workspace, click **Ingest** in the left sidebar.

    Click **New Ingest** at the top right.

    <Frame>
      <img alt="Ingest page with New Ingest at the top right" />
    </Frame>
  </Step>

  <Step title="Choose Git Repository">
    Scroll down to **Experimental** and click **Git Repository**.

    <Frame>
      <img alt="Git Repository card in the Experimental section of the ingest options" />
    </Frame>
  </Step>

  <Step title="Choose your connection and repository">
    In **GitHub connector**, select your saved GitHub connection.

    In **Repository**, choose the repository you want to add. For this example, choose `sphinx-ml/docs`.

    Choose the connection you named earlier: `GitHub documentation demo` in this example.
  </Step>

  <Step title="Write a detailed focus prompt">
    In **Focus prompt**, explain what you want Sphinx to learn and give it the context it needs to understand your repository.

    <Tip>
      **Take time to write a detailed, specific prompt.** A high-quality focus prompt helps Sphinx find the right information and preserve the details your team needs. Include useful context and concrete questions, rather than just asking it to “summarize the repository.”
    </Tip>

    You do not need to write code. In plain language, include:

    * **Your goal:** Who will use this knowledge, and what should it help them do?
    * **Where to look:** Name important topics, folders, or files if you know them.
    * **Context:** Explain unfamiliar terms and identify which information is current or most reliable.
    * **Details to keep:** Call out rules, calculations, exceptions, dependencies, or setup steps that matter.
    * **Questions to answer:** Give a few real questions you want Sphinx to be able to answer afterward.

    For the documentation repository in this guide, a detailed prompt could look like this:

    ```text theme={null}
    Help customer-facing teammates explain how customers connect Claude
    and ChatGPT to Sphinx. The knowledge should support someone walking
    a non-technical customer through setup.

    Start with the guides in claude/, claude-code-cli/,
    claude-desktop/, and chatgpt-desktop/. Follow related guides when
    they explain a prerequisite or a step in the same setup process.

    Keep the instructions for each client separate. Explain the
    difference between connecting to Sphinx MCP and using the Sphinx
    LLM Gateway, based on the repository's guides.

    Preserve prerequisites, exact button names, configuration values,
    sign-in steps, actions that need an administrator, and how users
    check that the connection worked. Include documented troubleshooting.
    If guides disagree or leave a step unclear, call that out instead
    of guessing.

    The knowledge should answer:
    - What does a customer need before starting each setup?
    - What should they click and enter, in order?
    - Which steps need help from an administrator?
    - How do they confirm that setup worked?
    ```

    <Accordion title="Example for an internal analytics dashboard repository">
      Use this example if your team builds internal analytics dashboards. Add the dashboard names, business topics, and folders that matter to your team.

      ```text theme={null}
      This repository contains our internal analytics dashboards. Help
      our teammates understand what each dashboard shows, how its numbers
      are calculated, and how to use them to answer business questions.
      We want Sphinx's knowledge to reflect the repository as it evolves.

      Focus on dashboard definitions, charts, queries, data models, and
      related documentation. Follow supporting code, configuration, and
      tests when they explain a calculation or business rule.

      For each dashboard, explain its purpose, intended audience, and
      the business questions it answers. Preserve chart and metric names
      so teammates can match the explanation to what they see on screen.

      For each metric, explain its business meaning, calculation, source
      tables, filters, exclusions, and time period. Explain how tables
      connect, what one row represents, and how dates and time zones
      affect the result. Include these details when the repository
      provides them; flag anything unclear instead of guessing.

      Explain how dashboard filters, default selections, and drill-downs
      change the numbers. Include documented refresh schedules, data
      delays, limitations, and reasons similar charts may disagree.

      On each ingest, use the current repository definitions. Capture
      new dashboards and changed calculations, filters, or business
      rules. Identify deprecated dashboards and metrics where the
      repository marks them as such. Include relevant file paths so
      teammates can find the source of an explanation.

      The knowledge should answer:
      - Which dashboard should I use for my business question?
      - What does this metric mean, and how is it calculated?
      - What data is included or excluded?
      - How do filters and date ranges affect the result?
      - How fresh is the data, and what limitations should I know?
      ```
    </Accordion>

    Adapt these examples to your repository. **Specificity matters more than length:** include the context you know and the details you need, without adding unrelated instructions. Explain the business meaning you want to capture, rather than asking for a file-by-file code summary.

    <Frame>
      <img alt="Git Repository form with a saved connector, sphinx-ml/docs repository, a detailed focus prompt, and Create ingest button" />
    </Frame>
  </Step>

  <Step title="Create the ingest">
    Check that the repository and focus prompt are correct, then click **Create ingest** once.

    Sphinx opens a page where you can follow its progress. You can also find the job later under **Ingest**.

    When **Review Changes** appears, click it to read the proposed knowledge before accepting it.
  </Step>
</Steps>

## If you get stuck

<AccordionGroup>
  <Accordion title="GitHub did not open, or I closed the tab">
    Go to **Settings → Connectors** and open your connector.

    Click **Install GitHub App** to finish installation, or **Sign in with GitHub** to finish signing in. You do not need to create another connector.
  </Accordion>

  <Accordion title="GitHub says I need an organization owner">
    Ask the person who manages your company's GitHub account to complete the app setup for your repository. Return to Sphinx afterward and refresh the connector page.

    If the app already has access but Sphinx still shows **Install GitHub App**, ask the Sphinx team for help connecting that existing installation.
  </Accordion>

  <Accordion title="My repository is missing">
    Check that you selected the right GitHub connector and signed in with an account that can access the repository.

    Open the connector and use **Manage GitHub App** to check that your repository is included. Ask your GitHub administrator for help if you cannot change this. Then reload the ingest page and select the connector again.
  </Accordion>

  <Accordion title="My connector is missing">
    Check the **Workspace** in Settings. Use the same workspace where you created the connector.
  </Accordion>

  <Accordion title="Git Repository is missing">
    Ask the Sphinx team to enable Git ingest for your workspace. Include your workspace's name.
  </Accordion>

  <Accordion title="Create ingest is greyed out">
    Make sure you selected a connected **GitHub connector**, chose a **Repository**, and entered a **Focus prompt**.
  </Accordion>

  <Accordion title="Which version of my files will Sphinx read?">
    Sphinx reads the repository's default branch—the version GitHub normally shows when you open the repository. There is no branch selector on the ingest page.
  </Accordion>

  <Accordion title="I need help with an ingest">
    Share the job ID, repository name, and any error message with the Sphinx team. If knowledge is missing, give one example of what you expected Sphinx to learn.
  </Accordion>
</AccordionGroup>


# Sphinx overview
Source: https://docs.sphinx.ai/overview

Learn how Sphinx helps organizations improve the accuracy, consistency, and traceability of AI-generated data outputs.

## What is Sphinx?

Sphinx is a governance and reliability layer between your AI tools and data stack. It helps ensure that AI-generated answers follow your business definitions, use the right data, and remain traceable.

## What Sphinx does

* Builds a shared knowledge base from your schemas, metrics, business logic, and institutional knowledge.
* Validates AI queries and catches drift, inconsistencies, and hallucinations.
* Traces outputs back to their source data, logic, and reasoning.
* Adds access controls, audit logs, and configurable human approval.

<Card title="Stay up to date" href="https://sphinx.ai/">
  To see more, check out the current Sphinx website.
</Card>

<Card title="Connect GitHub and add a repository" icon="github" href="/git-ingest">
  Follow the screenshots to connect GitHub and add repository knowledge to Sphinx.
</Card>


# .fit Reference
Source: https://docs.sphinx.ai/python-sdk/fit



## Requirements

* Python **3.13 or later**.
* An existing Sphinx project.
* An API key provided to you by Sphinx.

The package name is `sphinx_learn`. The Python import name is `sphinx_ai`.

## createKnowledgeBaseClient

`createKnowledgeBaseClient(api_key: str, project_id: str) -> KnowledgeBaseClient`

| Parameter | Description |
| - | - |
| `api_key` | The API key provided to you by Sphinx. |
| `project_id` | The existing project that receives the ingest job. |

## Document

A document is an input to an ingest job. Currently, the supported document type is:

* [`File`](#file): A document supplied as bytes with a source filename or path.

## File

`File(path: str, content: bytes)`

`File` is immutable. Its constructor validates the path and content immediately, raising `TypeError` for incorrect types or `ValueError` for invalid values. Create a new `File` to change its path or content.

| Field | Description |
| - | - |
| `path` | Source filename or relative path, including the extension when applicable. This is an identifier, not a URL to fetch or a local path the SDK opens. |
| `content` | The document as bytes. For text, make sure it is UTF-8 encoded. |

## KnowledgeBaseClient.fit

`knowledge_base.fit(prompt: str, docs: list[Document]) -> Ingestion`

| Parameter | Description |
| - | - |
| `prompt` | Instructions for ingesting the documents. |
| `docs` | A Python list of documents to ingest in one job. See [Document](#document) for supported types. |

The method validates the prompt, document types, document count, and total content size before uploading, uploads documents sequentially, and then submits one `agentic_ingest` job. Leading and trailing whitespace is removed from the prompt when the job is submitted.

### Input constraints

These limits are enforced locally before any upload. Per-file constraints are checked when you construct each `File`; prompt and batch constraints are checked by `.fit`. Size and count limits are inclusive.

| Input | Constraint |
| - | - |
| `prompt` | Must be a string containing non-whitespace text, with at most **10,000 characters** before trimming. |
| `docs` | Must be a Python `list` containing **1–20,000** `File` objects. Tuples, generators, dictionaries, and filenames alone are not accepted. |
| `File.path` | Must be a string of **1–512 characters** using only the characters and path segments described below. |
| `File.content` | Must be `bytes`, not a string, file handle, or `bytearray`. |
| Total content size | At most **2.5 GiB (2,684,354,560 bytes)** across all documents in one call, measured from the raw content. |
| Supported binary file size | At most **100 MiB (104,857,600 bytes)** per file with a supported binary extension. |
| Text file size | At most **4 MiB (4,194,304 bytes)** per text file. |
| Text token estimate | At most **250,000 estimated tokens** per text file, calculated as the decoded character count divided by four, rounded up. |
| Content format | Must have a supported binary extension or contain valid UTF-8 text without null bytes. |
| Structured text | `.json`, `.jsonl`, `.ndjson`, and `.ipynb` must also satisfy the format checks below. |

Text files must satisfy both the byte-size and estimated-token limits. The token estimate allows at most **1,000,000 decoded characters** per file; it is not a model-specific tokenizer count. An optional UTF-8 byte-order mark counts toward the byte size but is excluded from the decoded character count. The text limits apply to files without a supported binary extension, regardless of their filename.

#### Source paths

Allowed characters are ASCII letters (`A–Z`, `a–z`), digits (`0–9`), and:

```text theme={null}
! - _ . * ' ( ) /
```

Use `/` to separate path segments. Empty segments and segments equal to `.` or `..` are rejected. Consequently, paths cannot start or end with `/` or contain `//`. Spaces, backslashes, colons, and non-ASCII characters are also rejected.

| Valid | Invalid | Reason |
| - | - | - |
| `handbook.pdf` | `company handbook.pdf` | Space in the filename. |
| `policies/leave.md` | `/policies/leave.md` | Leading slash creates an empty segment. |
| `reports/2026/revenue.csv` | `reports/../revenue.csv` | `..` segment. |
| `notes/team-a.txt` | `notes//team-a.txt` | Empty segment between slashes. |

#### Supported formats

| Format | Extensions or requirements |
| - | - |
| PDF | `.pdf` |
| Word | `.doc`, `.docx` |
| PowerPoint | `.ppt`, `.pptx` |
| Images | `.png`, `.jpg`, `.jpeg` |
| Spreadsheets | `.xlsx`, `.ods` |
| Text | Valid UTF-8, optionally with a UTF-8 byte-order mark, and no null bytes. Examples include `.txt`, `.md`, `.csv`, `.json`, and source code. |
| JSON | `.json` must parse as JSON. |
| JSON Lines | `.jsonl` and `.ndjson`: each nonblank line must parse as JSON. Blank lines are ignored. |
| Jupyter notebooks | `.ipynb` must parse as a JSON object containing a `cells` list. Every cell must be an object. |

Extension checks are case-insensitive. Any extension outside the binary list, or no extension, takes the text-validation path. For example, a binary `.xls` or ZIP archive will fail text validation; `.xlsx` and `.ods` are the supported binary spreadsheet formats. A filename consisting only of an extension, such as `.pdf`, is treated as having no extension.
For the listed binary extensions, the client does not inspect whether the bytes form a valid document. A corrupt or mislabeled file can pass local validation and fail during ingestion. Renaming an unsupported binary file does not convert it to a supported format. MIME types are inferred from the filename, with `application/octet-stream` as the fallback.

### Failure handling

| Error or symptom | What to check |
| - | - |
| `TypeError` | Check the parameter types, especially `docs` as a list, each item as a `File`, and `content` as bytes. |
| `ValueError` | Read the validation message for the invalid prompt, path, document count, total size, per-file size, text token estimate, text encoding, JSON, or notebook structure. Fix it before retrying. |
| `RuntimeError` beginning with `Failed to upload` | An upload returned a non-2xx HTTP status. The message identifies the file and HTTP response. No ingest job has been submitted by this call. |
| API or network exception | Check connectivity, API key validity, and the project ID. These errors propagate from the underlying clients. |
| Job URL returned, but ingestion fails later | Open the job URL to inspect the job. Returning a URL confirms submission, not successful processing. |

## Ingestion.job\_url

`ingestion.job_url() -> str`

Returns the job's Sphinx UI URL.


# Run your first ingest job
Source: https://docs.sphinx.ai/python-sdk/quickstart

Install sphinx_learn, submit your first documents with .fit, and follow the ingest job in Sphinx.

Use this quickstart to submit a document to your Sphinx knowledge base with `.fit` and open the resulting ingest job. The example supplies its own text, so you do not need a local document to get started.

## Prerequisites

* Python **3.13 or later**.
* An existing Sphinx project and its project ID.
* An API key provided to you by Sphinx.
* Network access to the Sphinx API and the upload URLs it provides.

Sphinx will provide your API key. Keep the key in an environment variable rather than embedding it in your script.

## 1. Install the library

The package name is `sphinx_learn`. Once the package is published, install it with:

```bash theme={null}
python -m pip install sphinx_learn
```

## 2. Submit an ingest job

Set `SPHINX_API_KEY` and `SPHINX_PROJECT_ID` in your environment, then run:

```python theme={null}
import os

from sphinx_ai import File, createKnowledgeBaseClient

knowledge_base = createKnowledgeBaseClient(
    api_key=os.environ["SPHINX_API_KEY"],
    project_id=os.environ["SPHINX_PROJECT_ID"],
)

ingestion = knowledge_base.fit(
    prompt=(
        "Learn a knowledge graph that helps us understand how metrics are defined at our company."
    ),
    docs=[
        File(
            path="metrics/active-customers.txt",
            content=(
                "An active customer is an account with at least one paid order "
                "in the last 30 days. Exclude test accounts and canceled orders."
            ).encode("utf-8"),
        ),
    ],
)

print(ingestion.job_url())
```

## 3. Follow the job in Sphinx

`File(...)` validates each document's path and content immediately. `.fit(...)` checks the prompt and batch limits before uploading. See [input constraints](/python-sdk/fit#input-constraints) when preparing your own documents.

The script prints a URL with this structure:

```text theme={null}
https://app.sphinx.ai/knowledge-base/projects/<project_id>/ingest/<job_id>
```

Open the URL to check the job's progress and results. The prompt tells the ingest job what you want to do with the documents; it is not a guarantee of a particular output.

<Note>
  `.fit` returns after uploading the documents and submitting the job. Ingestion continues separately. Check the job in Sphinx to confirm it completed successfully and review the results.
</Note>

## Next steps

See [Using .fit library](/python-sdk/fit) for the API reference, supported formats, exact input limits, and failure handling.