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

# Claude Code

> Connect StackOne MCP to Claude Code with OAuth using built-in MCP commands.

## Overview

[Claude Code](https://code.claude.com/) is Anthropic's CLI for developers. It has built-in commands for managing MCP servers and runs the OAuth flow itself.

<Info>
  For complete Claude Code MCP documentation, see the [official MCP guide](https://code.claude.com/docs/en/mcp).
</Info>

## Prerequisites

* A StackOne [project](/gateway/concepts/organizations-and-projects) you are a member of.
* A [connector profile](/gateway/concepts/connector-profiles) in the project for each provider the client should reach, with the actions you want exposed enabled.
* (Optional) A [linked account](/gateway/concepts/linked-accounts) for each provider. Accounts can also be linked during the consent flow.

## Setup

<Steps>
  <Step title="Add the StackOne MCP server">
    ```bash theme={null}
    claude mcp add --transport http stackone https://mcp.stackone.com/mcp
    ```

    <Tip>
      Add `--scope user` to make it available across all your projects rather than just the current directory. See [Scope options](#scope-options).
    </Tip>
  </Step>

  <Step title="Authenticate">
    Claude Code waits for you to ask before opening a browser. Run `/mcp`, select **stackone**, then **Authenticate**.

    Sign in, pick the project and the [linked accounts](/gateway/concepts/linked-accounts) the connector should reach, then **Authorize**.

    <Accordion title="Walk through the consent screen">
      1. **Sign in to StackOne.** If you are already signed in to the dashboard you skip straight to the next step.
      2. **Select a project.** Select the project you would like to associate the connection with.
      3. **Select accounts and actions.** Existing linked accounts are shown. New accounts can be linked by clicking **+ Link Account**. You can either select the whole account (all actions will be granted) or refine by toggling individual actions.
      4. **(Optional) Load tools when needed.** On by default, and the toggle that puts the connection into [Advanced Tool Search](/optimize/advanced-tool-search). Leave it on for large action sets. Turn it off to hand the agent every selected action up front.
      5. **Authorize.** Completes the connection; you can return to your client.

      <Columns cols={3}>
        <Frame caption="Select a project">
          <img src="https://mintcdn.com/stackone-60/09ChgExN01gpADnF/images/mcp/oauth-consent-select-project.png?fit=max&auto=format&n=09ChgExN01gpADnF&q=85&s=de028c13efd3deb163e7e6df2d5d5a22" alt="StackOne authorization screen listing organizations, with a project selected inside one of them" style={{ width: '100%', aspectRatio: '780 / 877', objectFit: 'cover' }} width="1294" height="924" data-path="images/mcp/oauth-consent-select-project.png" />
        </Frame>

        <Frame caption="Select accounts">
          <img src="https://mintcdn.com/stackone-60/0prlrmjeswzs-fZr/images/mcp/oauth-consent-select-accounts.png?fit=max&auto=format&n=0prlrmjeswzs-fZr&q=85&s=cdcf3d79600332d06113ed75c55c0225" alt="StackOne authorization screen showing two linked accounts, Linear and Open-Meteo, both selected, above the Load tools when needed toggle" width="1560" height="1754" data-path="images/mcp/oauth-consent-select-accounts.png" />
        </Frame>

        <Frame caption="Toggle actions">
          <img src="https://mintcdn.com/stackone-60/0prlrmjeswzs-fZr/images/mcp/oauth-consent-select-actions.png?fit=max&auto=format&n=0prlrmjeswzs-fZr&q=85&s=9f1246d1991b50c33cbd161b07d5ca77" alt="An expanded linked account showing individual actions with toggles, descriptions, and category tags" width="1560" height="1754" data-path="images/mcp/oauth-consent-select-actions.png" />
        </Frame>
      </Columns>

      <Note>
        If you see a sentence where the **Load tools when needed** toggle should be, an admin has already settled it for the whole project. See [project settings](/optimize/advanced-tool-search#setting-it-for-a-whole-project).
      </Note>
    </Accordion>
  </Step>

  <Step title="Verify connection">
    Check the server status:

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

    Within a session, use `/mcp` to view server details and available tools, then select **View tools** to browse the operations you granted.
  </Step>
</Steps>

One grant covers every account you approved, so a single `stackone` server is usually all you need. To change which accounts or actions it can reach, re-run `/mcp` and authenticate again; to revoke it, use **Connected Apps** in the StackOne dashboard.

## Scope options

Control where the configuration is stored:

| Scope   | Flag              | Storage location                    | Use case                                |
| ------- | ----------------- | ----------------------------------- | --------------------------------------- |
| Local   | (default)         | `.claude.json` in current directory | Project-specific                        |
| Project | `--scope project` | `.mcp.json` at project root         | Team collaboration (version controlled) |
| User    | `--scope user`    | `~/.claude.json`                    | Personal tools across all projects      |

**Example with user scope** (available across all projects):

```bash theme={null}
claude mcp add --transport http --scope user stackone https://mcp.stackone.com/mcp
```

<Note>
  A `--scope project` entry is safe to commit, because the URL carries no access of its own. Each teammate authenticates as themselves and gets their own accounts.
</Note>

## Management commands

```bash theme={null}
claude mcp list              # View all configured servers
claude mcp get stackone      # Show details for a specific server
claude mcp remove stackone   # Remove a server
```

<Accordion title="Connecting with a session token instead" icon="key">
  A session token URL carries its own credential, so it covers the cases OAuth can't: a shared server, a scheduled job, or anywhere nobody is present to approve a consent screen.

  Generate one from **Connectors**, open a connector, then **Use in Agent**. Pick a linked account, set the expiry (one year by default), and copy the URL:

  ```
  https://api.stackone.com/mcp?token={session_token}
  ```

  One URL covers one linked account, and anyone holding it has that access until it expires, so treat it like a password. See [Choosing a connection method](/connect/ai-platforms/overview#choosing-a-connection-method) for the comparison with OAuth.

  There is no consent screen to set [Advanced Tool Search](/optimize/advanced-tool-search) on, so add the `tool-mode` query parameter instead:

  ```
  https://api.stackone.com/mcp?token={session_token}&tool-mode=search_execute
  ```

  Pass the token URL to `claude mcp add`, one server per linked account:

  ```bash theme={null}
  claude mcp add \
    --transport http \
    gsheets \
    "https://api.stackone.com/mcp?token={session_token}"
  ```

  <Tip>
    Use short names for easier CLI usage: `gsheets`, `slack`, `hubspot-sales`.
  </Tip>

  For multiple accounts, get a separate token for each and add them as distinct servers:

  ```bash theme={null}
  claude mcp add --transport http gsheets "https://api.stackone.com/mcp?token={google_sheets_session_token}"
  claude mcp add --transport http slack "https://api.stackone.com/mcp?token={slack_session_token}"
  ```

  <Accordion title="Alternative: manual API key setup">
    If you prefer to use your API key and account ID directly, set your encoded API key as an environment variable first:

    <Tabs>
      <Tab title="macOS / Linux">
        ```bash theme={null}
        export STACKONE_AUTH_TOKEN=$(echo -n "{stackone_api_key}:" | base64)
        ```
      </Tab>

      <Tab title="Windows (PowerShell)">
        ```powershell theme={null}
        $env:STACKONE_AUTH_TOKEN = [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes("{stackone_api_key}:"))
        ```
      </Tab>
    </Tabs>

    Then add the server:

    ```bash theme={null}
    claude mcp add \
      --transport http \
      --header "Authorization: Basic $STACKONE_AUTH_TOKEN" \
      gsheets \
      "https://api.stackone.com/mcp?x-account-id={account_id}"
    ```
  </Accordion>
</Accordion>

## Programmatic integration

For programmatic integration with Anthropic's Claude API, see the [Anthropic SDK Framework Guide](/embed/call-actions/mcp/anthropic-sdk).

## Optimize and secure

With your agent connected, use StackOne's platform features to optimize performance and secure every call.

<CardGroup cols={2}>
  <Card title="Advanced Tool Search" icon="magnifying-glass" href="/optimize/advanced-tool-search">
    Reduce context and save tokens.
  </Card>

  <Card title="Deep Query" icon="magnifying-glass-chart" href="/optimize/deep-query">
    Search synced records for a fraction of the tokens.
  </Card>

  <Card title="Defender" icon="shield-halved" href="/secure/defender">
    Block prompt injections before they reach your agent.
  </Card>
</CardGroup>