> ## 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 server to Goose AI assistant for automated workflows and on-machine AI assistance.

## Overview

[Goose](https://block.github.io/goose/) is an on-machine AI agent (CLI and Desktop) from Block with MCP support.

## Prerequisites

* Goose installed ([installation guide](https://block.github.io/goose/docs/getting-started/installation/))
* A StackOne linked account ([set one up here](/guides/auth-link))

## Get your MCP URL

Before configuring Goose, get your MCP URL from the StackOne dashboard:

1. Go to **Connectors** in the left nav and open the connector you want to use
2. Click **Use Connector** in the top right
3. On the **Use** tab, click **MCP Server** under "Use with Agent Client"
4. Select a linked account from the dropdown
5. Choose **HTTPS MCP** as the client
6. Copy the generated URL — it looks like:
   ```
   https://api.stackone.com/mcp?token=<session_token>
   ```

The token encodes your account identity. No separate API key or account ID header is needed.

<Tip>
  The token expires after one year. Regenerate it at any time using the refresh button in the MCP tile.
</Tip>

***

## Setup Methods

Goose supports two methods: **Interactive Configuration** (easiest) and **Manual YAML** (advanced).

***

## Method 1: Interactive Configuration (Recommended)

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"** — StackOne uses HTTP transport.
  </Step>

  <Step title="Name Your Extension">
    Enter a name: `stackone` (or any name you prefer).
  </Step>

  <Step title="Enter Server URL">
    Paste the URL from the dashboard:

    ```
    https://api.stackone.com/mcp?token=<session_token>
    ```
  </Step>

  <Step title="Enable Extension">
    When asked if you want to enable the extension, select **"Yes"**.
  </Step>
</Steps>

***

## Method 2: 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: http
    url: https://api.stackone.com/mcp?token=<session_token>
    enabled: true
    timeout: 300
```

Replace `<session_token>` with the token from the dashboard.

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

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

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

***

## Advanced: Manual API Key Setup

If you prefer to authenticate with your API key and account ID directly:

```yaml theme={null}
extensions:
  stackone:
    name: stackone
    type: 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
```

Using environment variables:

```yaml theme={null}
extensions:
  stackone:
    name: stackone
    type: http
    url: https://api.stackone.com/mcp
    enabled: true
    timeout: 300
    headers:
      Authorization: "Basic ${STACKONE_AUTH_TOKEN}"
      x-account-id: "${STACKONE_ACCOUNT_ID}"
```

See [Authentication & Security](/mcp/auth-security) for details.

***

## Verify Installation

After configuration, start a Goose session and check available tools:

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

Then ask:

```
what tools do you have?
```

You should see StackOne operations based on your connected accounts.

***

## Desktop Application

If using Goose Desktop:

1. Open Goose Desktop
2. Go to **Settings** → **Extensions**
3. Your StackOne extension should appear in the list
4. Toggle to enable/disable as needed

***

## 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 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. Verify you have active integrations in the StackOne Dashboard
    2. Check that actions are enabled in your integration config
    3. Review [StackOne Playground](https://app.stackone.com/playground) to see expected tools
  </Accordion>

  <Accordion title="YAML configuration errors">
    1. Validate YAML syntax at [https://www.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>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Dashboard Setup" icon="desktop" href="/mcp/connect-from-dashboard">
    Generate MCP configs from any connector
  </Card>

  <Card title="Authentication Guide" icon="lock" href="/mcp/auth-security">
    Configure authentication and security
  </Card>

  <Card title="Goose Documentation" icon="book" href="https://block.github.io/goose/docs/">
    Learn more about Goose capabilities
  </Card>

  <Card title="Explore All Tools" icon="grid" href="https://app.stackone.com/playground">
    See all available operations in StackOne Playground
  </Card>
</CardGroup>