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

# Connect Your AI Tool

> Authorize Claude Code, Codex, ChatGPT, Gemini CLI, Cursor, or other MCP clients to access your Stardeck organization.

## Before you begin

You'll need:

* A **Stardeck account** and membership in the org you want to connect to
* A **role** to bind the connection to — see [Members & Roles](/members-and-roles). Pick the least permissive role that covers what you need.
* Access to your org's **[Settings → AI Integrations](https://www.stardeck.ai/dashboard/settings?tab=ai-integrations)** tab

## The authorization flow

Every connection goes through a one-time browser authorization:

1. Your AI client discovers the Stardeck MCP server (you provide the URL)
2. Stardeck opens a browser page where you sign in, pick an org, pick a role, and choose read or read+write access
3. Your client receives a token and is ready to use

The server URL is the same for every client:

```
https://www.stardeck.ai/api/mcp
```

After authorization you can change the role or access level — or revoke access entirely — from the **AI Integrations** tab in your org's Settings. You don't need to re-authorize to change the role; the change takes effect on the next tool call.

## Client-specific setup

<Tabs>
  <Tab title="Claude Code">
    Claude Code (the CLI) supports OAuth MCP servers natively.

    ### Add the server

    Run this command once in your terminal — you can run it from any directory:

    ```bash theme={null}
    claude mcp add --transport http stardeck https://www.stardeck.ai/api/mcp
    ```

    This writes an entry to your global `~/.claude/claude_desktop_config.json` (or the project-level `.mcp.json` if you prefer scoping it to a single checkout). Name it whatever you like — `stardeck` is conventional.

    ### Authorize

    Next time you open Claude Code, it will prompt you to approve the new server and then open your browser to sign in. Complete the authorization there.

    To trigger it immediately:

    ```bash theme={null}
    claude
    ```

    Then type `/mcp` to see connected servers and their status. A `stardeck` entry with a green indicator means it's live.

    ### Verify

    Ask Claude something like:

    > *List the items in my knowledge store*

    or:

    > *What apps does my org have?*

    If you get real data back, you're connected.

    <Note>
      The `stardeck` server here is the **org-level** connection. If you're also using Claude Code for local development on a specific app, you may have a separate project-level connection in your app's `.mcp.json` — that's a different server scoped to that one project. Both can be active at the same time.
    </Note>
  </Tab>

  <Tab title="Codex">
    Codex CLI supports remote Streamable HTTP MCP servers and OAuth. See
    [OpenAI's MCP guide](https://learn.chatgpt.com/docs/extend/mcp) for the
    shared Codex and ChatGPT configuration model.

    ### Add the server

    Run this command once in your terminal:

    ```bash theme={null}
    codex mcp add stardeck --url https://www.stardeck.ai/api/mcp
    ```

    ### Authorize

    Start the OAuth flow:

    ```bash theme={null}
    codex mcp login stardeck
    ```

    Complete the Stardeck sign-in in your browser. The connection is saved in
    `~/.codex/config.toml` and is also available to the Codex IDE extension and
    the ChatGPT desktop app.

    ### Verify

    Run `codex mcp list` to check the server, or type `/mcp` inside Codex to see
    its status. Then ask Codex something like:

    > *List the items in my knowledge store*
  </Tab>

  <Tab title="Claude Desktop">
    Claude Desktop and Claude Web (claude.ai) both support OAuth MCP servers.

    ### Claude Desktop

    Open **Settings → Developer → MCP Servers** and add:

    ```json theme={null}
    {
      "mcpServers": {
        "stardeck": {
          "type": "http",
          "url": "https://www.stardeck.ai/api/mcp"
        }
      }
    }
    ```

    Restart Claude Desktop. On next launch it will prompt you to authorize — click through to the browser sign-in and complete it.

    ### Claude Web (claude.ai)

    In Claude Web, open **Settings → Integrations** and add a custom integration. Paste `https://www.stardeck.ai/api/mcp` as the server URL. Claude will open the browser authorization flow for you.

    ### Verify

    Once authorized, open a new conversation and ask:

    > *What's in my Stardeck knowledge store?*

    Common tools and catalog helpers appear directly; Claude discovers other authorized capabilities through Stardeck's tool catalog. See [Tools & Permissions](/ai-integrations/tools#how-tools-are-disclosed).
  </Tab>

  <Tab title="Cursor">
    Cursor supports MCP servers via its settings file.

    Open **Settings → Cursor Settings** (or `Cmd/Ctrl + Shift + J`) and navigate to the **MCP** section. Add a new server:

    ```json theme={null}
    {
      "mcpServers": {
        "stardeck": {
          "type": "http",
          "url": "https://www.stardeck.ai/api/mcp"
        }
      }
    }
    ```

    Save and reload Cursor. It will open your browser to complete the OAuth authorization.

    After authorization, common tools and catalog helpers appear in the Cursor agent's tool list. Other authorized capabilities are discovered through Stardeck's tool catalog — see [Tools & Permissions](/ai-integrations/tools#how-tools-are-disclosed). Ask the agent to list your org's knowledge or data stores to confirm it's working.
  </Tab>

  <Tab title="ChatGPT">
    The ChatGPT desktop app supports remote MCP servers with OAuth. See
    [OpenAI's MCP guide](https://learn.chatgpt.com/docs/extend/mcp) for the
    current server settings. This setup uses ChatGPT's MCP server settings —
    not GPT Actions.

    ### Add the server

    1. Open the ChatGPT desktop app and go to **Settings → MCP servers**

    2. Select **Add server**

    3. Name the server `Stardeck`, choose **Streamable HTTP**, and enter:

       ```
       https://www.stardeck.ai/api/mcp
       ```

    4. Save the server and restart ChatGPT if prompted

    ### Authorize and verify

    In **Settings → MCP servers**, select **Authenticate** for Stardeck and
    complete the browser sign-in. In a new conversation, type `/mcp` to check
    the connection, then ask:

    > *What's in my Stardeck knowledge store?*

    <Note>
      ChatGPT web uses hosted apps or workspace-installed plugins rather than a
      raw MCP URL in a custom GPT. If Stardeck is available in your ChatGPT
      workspace as an app, use that app entry; otherwise use the ChatGPT desktop
      app instructions above.
    </Note>
  </Tab>

  <Tab title="Gemini CLI">
    Gemini CLI supports MCP servers via its configuration file.

    Open (or create) `~/.gemini/config.json` and add:

    ```json theme={null}
    {
      "mcpServers": {
        "stardeck": {
          "httpTransport": {
            "url": "https://www.stardeck.ai/api/mcp"
          }
        }
      }
    }
    ```

    On next launch, Gemini CLI will prompt you to authorize — open the browser link it prints and complete the Stardeck sign-in.

    Confirm the connection with:

    ```bash theme={null}
    gemini
    ```

    Then ask: *What's in my Stardeck knowledge store?*
  </Tab>
</Tabs>

## Managing connections

All active connections appear in **[Settings → AI Integrations](https://www.stardeck.ai/dashboard/settings?tab=ai-integrations)** in your org dashboard. From there you can:

* **Change the role** the connection acts as — takes effect immediately, no re-authorization needed
* **Change the access level** (read only ↔ read & write)
* **Revoke access** — the connection stops working on its next request

Members can always manage their own connections. To manage another member's connections, you need the **Manage AI Connectors** system permission.

## Troubleshooting

### Authorization opens but shows an error after sign-in

Make sure you're signed into the Stardeck organization you want to connect. If you belong to multiple orgs, pick the right one in the org picker.

### "This connector has no tools available"

The role you picked doesn't hold any agent permissions. Go to **[Settings → AI Integrations](https://www.stardeck.ai/dashboard/settings?tab=ai-integrations)**, change the role to one with `agent:*` permissions (e.g. a member or admin role), and the change takes effect immediately.

If common tools work but a specific capability seems missing from the direct tool list, it may be catalog-only — see [How tools are disclosed](/ai-integrations/tools#how-tools-are-disclosed).

### Tools appear but produce "Access denied" errors

The role has the right agent permission but the per-object check failed — for example, you're querying a data store the role doesn't have a grant for, or a knowledge item in a folder the role can't access. Check the data store's Access settings or the knowledge folder's permissions.

### Connection disappears after the next restart

Some clients require re-authorization if the server isn't reachable during startup. Make sure the Stardeck server URL is correct and that the token hasn't been revoked. Re-run that client's setup command if needed — for example, `claude mcp add ...` or `codex mcp add ...`.

## Next steps

<CardGroup cols={2}>
  <Card title="Tools & Permissions" icon="shield" href="/ai-integrations/tools">
    Full reference of tool groups and the permissions that unlock them
  </Card>

  <Card title="Members & Roles" icon="users" href="/members-and-roles">
    Create and configure roles for AI connections
  </Card>

  <Card title="Cross-App Communication" icon="right-left" href="/cross-app/overview">
    How apps call each other — the same mechanism the AI tools use
  </Card>

  <Card title="Starcat" icon="cat" href="/starcat">
    The in-dashboard agent that uses the same capabilities
  </Card>
</CardGroup>