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

# Quickstart

> Connect your agent to the Stoneturner MCP

# Connecting to Stoneturner

There are two ways to connect your agents to Stoneturner:

<Columns cols={2}>
  <Card title="Stoneturner hosted MCP" icon="cloud" href="/quickstart#stoneturner-hosted-mcp">
    We take care of data storage and incremental syncs so your agents can search your data from anywhere
  </Card>

  <Card title="Stoneturner Local" icon="computer" href="/quickstart#option-2-running-stoneturner-locally">
    Your data is privately synced to your local machine (or VPC) - **everything you can do on the Stoneturner hosted MCP is available, and all open source**
  </Card>
</Columns>

## Option 1: Stoneturner Hosted MCP

Just add Stoneturner to your agent config. That's it!

<Note>
  You can also start at [https://app.stoneturner.app](https://app.stoneturner.app) to start your syncs and connect your agent to the MCP after.

  You can also have the agents kick off syncs via the MCP, if you'd like your agent to set everything up.
</Note>

<Tabs>
  <Tab title="Claude Code">
    ```bash Claude CLI theme={null}
    claude mcp add --transport http stoneturner http://app.stoneturner.app/mcp
    ```

    ```json .mcp.json manual add theme={null}
    {
      "mcpServers": {
        "stoneturner": {
          "type": "remote",
          "url": "https://app.stoneturner.app/mcp"
        }
      }
    }
    ```
  </Tab>

  <Tab title="Codex">
    ```toml config.toml theme={null}
    [mcp_servers.stoneturner]
    url = "https://app.stoneturner.app/mcp"
    ```
  </Tab>

  <Tab title="OpenCode">
    ```json .config/opencode/opencode.jsonc theme={null}
    {
      "$schema": "https://opencode.ai/config.json",
      "mcp": {
        "stoneturner": {
          "type": "remote",
          "url": "https://app.stoneturner.app/mcp",
          "enabled":true
        }
      }
    }
    ```
  </Tab>

  <Tab title="ChatGPT">
    1. Go to [ChatGPT's App Settings](https://chatgpt.com/apps#settings/Connectors)
    2. Enable **Developer Mode**
    3. Create an app and make sure "Authentication" is set to **OAuth**
    4. Under "Connection" set it to:

    ```text Connection theme={null}
    https://app.stoneturner.app/mcp
    ```
  </Tab>

  <Tab title="Claude Web">
    1. Go to [Claude's Add Custom Connector](https://claude.ai/customize/connectors?modal=add-custom-connector)
    2. Give the connector a name (i.e. Stoneturner)
    3. Under "Remote MCP Server URL" set it to:

    ```text MCP URL theme={null}
    https://app.stoneturner.app/mcp
    ```
  </Tab>
</Tabs>

## Option 2: Running Stoneturner Locally

### Prerequisites

Before you begin, you must have:

* [ ] [Bun](https://bun.com) v1.3+
* [ ] [Vercel AI Gateway API key](https://vercel.com/ai-gateway) (used for embeddings)

### Setting up Stoneturner MCP locally

<img src="https://mintcdn.com/stoneturner/EYrS2jDoedV5MJ5Q/assets/agent-search.png?fit=max&auto=format&n=EYrS2jDoedV5MJ5Q&q=85&s=f23b4056a1f1af066c283e6b01b1ef26" alt="integrations" style={{borderRadius: "10px"}} width="2858" height="1826" data-path="assets/agent-search.png" />

<Steps>
  <Step title="Install">
    Clone the repository and install dependencies.

    ```bash theme={null}
    git clone https://github.com/jackmuva/stoneturner.git
    cd stoneturner
    bun install
    ```
  </Step>

  <Step title="Configure environment">
    Copy the example environment file and fill in your values.

    ```bash theme={null}
    cp .env.example .env
    ```

    | Variable                      | Required | Description                                                                                |
    | ----------------------------- | -------- | ------------------------------------------------------------------------------------------ |
    | `BUN_PUBLIC_BACKEND_BASE_URL` | Yes      | Backend URL, inlined at build time (e.g. `http://localhost:9000`)                          |
    | `FRONTEND_BASE_URL`           | Yes      | Frontend URL, used for CORS (e.g. `http://localhost:9000`)                                 |
    | `AI_GATEWAY_API_KEY`          | Yes      | API key for the AI gateway (embeddings)                                                    |
    | `BUN_PUBLIC_DEV_MODE`         | No       | Set to `true` to create a test database for developing new integrations (default: `false`) |
  </Step>

  <Step title="Set up the database">
    Generate and apply migrations. This creates a local `stoneturner.db` Turso/libSQL file — no remote database URL is needed for local development.

    ```bash theme={null}
    bun run generate
    bun run migrate
    ```
  </Step>

  <Step title="Run the dev server">
    Start the server with hot reload on port 9000.

    ```bash theme={null}
    bun run start
    ```
  </Step>
</Steps>

### Connect to Stoneturner

Configure an HTTP-based MCP in your agent config

<Tabs>
  <Tab title="Claude Code">
    ```bash Claude CLI theme={null}
    claude mcp add --transport http stoneturner http://localhost:9000/mcp
    ```

    ```json .mcp.json manual add theme={null}
    {
      "mcpServers": {
        "stoneturner": {
          "type": "remote",
          "url": "http://localhost:9000/mcp"
        }
      }
    }
    ```
  </Tab>

  <Tab title="Codex">
    ```toml config.toml theme={null}
    [mcp_servers.stoneturner]
    url = "http://localhost:9000/mcp"
    ```
  </Tab>

  <Tab title="OpenCode">
    ```json .config/opencode/opencode.jsonc theme={null}
    {
      "$schema": "https://opencode.ai/config.json",
      "mcp": {
        "stoneturner": {
          "type": "remote",
          "url": "http://localhost:9000/mcp",
          "enabled":true
        }
      }
    }
    ```
  </Tab>

  <Tab title="ChatGPT">
    1. Go to [ChatGPT's App Settings](https://chatgpt.com/apps#settings/Connectors)
    2. Enable **Developer Mode**
    3. Create an app and make sure "Authentication" is set to **OAuth**
    4. Under "Connection" set it to:

    ```text Connection theme={null}
    http://localhost:9000/mcp
    ```
  </Tab>

  <Tab title="Claude Web">
    1. Go to [Claude's Add Custom Connector](https://claude.ai/customize/connectors?modal=add-custom-connector)
    2. Give the connector a name (i.e. Stoneturner)
    3. Under "Remote MCP Server URL" set it to:

    ```text MCP URL theme={null}
    http://localhost:9000/mcp
    ```
  </Tab>
</Tabs>