> ## 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.

# Goose CLI & Desktop

> Connect StackOne MCP to the Goose AI assistant with OAuth.

## Overview

[Goose](https://goose-docs.ai) is an on-machine AI agent (CLI and Desktop) from Block with MCP support. It connects to remote servers over streamable HTTP as an extension.

## Prerequisites

* Goose installed ([installation guide](https://goose-docs.ai/docs/getting-started/installation))
* A StackOne project you're a member of

## Setup

Add StackOne's MCP endpoint. The URL is the whole configuration:

```
https://mcp.stackone.com/mcp
```

### Interactive configuration

Run the configuration wizard:

```bash theme={null}
goose configure
```

<Steps>
  <Step title="Select 'Add Extension'">
    When prompted, choose **Add Extension** from the menu.
  </Step>

  <Step title="Choose extension type">
    Select **Remote Extension (Streamable HTTP)**.
  </Step>

  <Step title="Name your extension">
    Enter `stackone` (or any name you prefer).
  </Step>

  <Step title="Enter the server URL">
    Paste `https://mcp.stackone.com/mcp`.
  </Step>

  <Step title="Approve the browser prompt">
    Goose opens StackOne in your browser. Sign in, pick the project and the [linked accounts](/gateway/concepts/linked-accounts) this machine should reach, then **Authorize**. See [Agent Setup](/connect/agent-setup/overview) for what the consent screen offers.
  </Step>
</Steps>

### Manual YAML configuration

Find your Goose config file:

* **Linux/Mac**: `~/.config/goose/config.yaml`
* **Windows**: `%APPDATA%\goose\config.yaml`

Add the following under `extensions`:

```yaml theme={null}
extensions:
  stackone:
    name: stackone
    type: streamable_http
    url: https://mcp.stackone.com/mcp
    enabled: true
    timeout: 300
```

Goose prompts for authorization the first time the extension loads. If it does not, use a session token URL instead.

One grant covers every account you approved, so a single `stackone` extension is usually all you need. To revoke it, use **Connected Apps** in the StackOne dashboard.

## Verify installation

Start a Goose session and check available tools:

```bash theme={null}
goose session
```

Then ask:

```text theme={null}
what tools do you have?
```

You should see StackOne operations for the accounts you approved.

## Desktop application

If using Goose Desktop, open **Settings → Extensions**. Your StackOne extension appears in the list, where you can toggle it on and off.

<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. [Session token URLs](/connect/agent-setup/overview#session-token-urls) compares the two.

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

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

  Put the token URL in the same `url` field, one extension per linked account:

  ```yaml theme={null}
  extensions:
    stackone:
      name: stackone
      type: streamable_http
      url: https://api.stackone.com/mcp?token=<session_token>
      enabled: true
      timeout: 300
  ```

  <Accordion title="Multiple accounts">
    Add separate entries for each account:

    ```yaml theme={null}
    extensions:
      salesforce:
        name: salesforce
        type: streamable_http
        url: https://api.stackone.com/mcp?token=<salesforce_session_token>
        enabled: true
        timeout: 300

      slack:
        name: slack
        type: streamable_http
        url: https://api.stackone.com/mcp?token=<slack_session_token>
        enabled: true
        timeout: 300
    ```
  </Accordion>

  <Accordion title="Alternative: manual API key setup">
    To authenticate with your API key and account ID directly:

    ```yaml theme={null}
    extensions:
      stackone:
        name: stackone
        type: streamable_http
        url: https://api.stackone.com/mcp
        enabled: true
        timeout: 300
        headers:
          Authorization: "Basic <YOUR_BASE64_TOKEN>"
          x-account-id: "<YOUR_ACCOUNT_ID>"
    ```

    To generate the base64 token:

    ```bash theme={null}
    echo -n "<stackone_api_key>:" | base64
    ```

    Environment variables work too:

    ```yaml theme={null}
    headers:
      Authorization: "Basic ${STACKONE_AUTH_TOKEN}"
      x-account-id: "${STACKONE_ACCOUNT_ID}"
    ```

    See [Authentication & Security](/embed/call-actions/mcp#calling-actions) for details.
  </Accordion>
</Accordion>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Extension not loading">
    **Symptoms:** StackOne tools don't appear when asked "what tools do you have?"

    1. Verify config file location: `goose info -v`
    2. Check YAML syntax (indentation matters)
    3. Ensure the extension is marked `enabled: true`
    4. Restart Goose after config changes
    5. Check logs: `goose logs`
  </Accordion>

  <Accordion title="Authentication errors">
    **Symptoms:** "401 Unauthorized" or "403 Forbidden"

    If you connected with OAuth, re-run `goose configure` to authorize again, and check the grant still exists under **Connected Apps** in the StackOne dashboard.

    If using a dashboard token, regenerate it from the MCP tile in the dashboard.

    If using manual API key auth:

    1. Verify base64 encoding includes the trailing colon: `echo -n "your_api_key:" | base64`
    2. Confirm the account ID matches your linked account
    3. Check the API key is valid in [StackOne Dashboard](https://app.stackone.com)
  </Accordion>

  <Accordion title="Connection timeout">
    Increase the timeout in your config:

    ```yaml theme={null}
    timeout: 600  # 10 minutes
    ```
  </Accordion>

  <Accordion title="No tools available">
    1. Confirm you approved at least one account on the consent screen
    2. Check that actions are enabled on the account's [connector profile](/gateway/concepts/connector-profiles)
    3. Review [StackOne Playground](https://app.stackone.com/playground) to see expected tools
  </Accordion>

  <Accordion title="YAML configuration errors">
    1. Validate YAML syntax at [yamllint.com](https://www.yamllint.com/)
    2. Check indentation (use spaces, not tabs)
    3. Ensure quotes around header values
    4. Run `goose info -v` to see config parsing errors
  </Accordion>
</AccordionGroup>

## Handling large tool catalogs

Granting a lot of actions produces a lot of tools, which costs context on every turn. **Search & Execute** replaces one-tool-per-action with two tools, search and execute, so the footprint stays flat however large the catalog.

Turn it on with the **Search & Execute mode** toggle on the consent screen when you authorize. A project admin can also set it for everyone, in which case the consent screen shows the decision instead of the toggle.

See [Tool Discovery](/features/tool-discovery) for how search works, its accuracy, and the other modes.

## Optimize and secure

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

<CardGroup cols={2}>
  <Card title="Search & Execute" icon="magnifying-glass" href="/optimize/search-and-execute">
    Reduce context and save tokens.
  </Card>

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