Goose CLI & Desktop

Overview

Goose is an on-machine AI agent (CLI and Desktop) from Block with MCP support.

Prerequisites

Goose installed (installation guide)
A StackOne linked account (set one up here)

Get your MCP URL

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

Go to Connectors in the left nav and open the connector you want to use
Click Use in Agent in the top right
On the Use tab, click MCP Server under “Use with Agent Client”
Select a linked account from the dropdown
Choose HTTPS MCP as the client

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.

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

Setup methods

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

Method 1: interactive configuration (recommended)

Run the configuration wizard:

goose configure

Select 'Add Extension'

When prompted, choose “Add Extension” from the menu.

Choose Extension Type

Select “Remote Extension” — StackOne uses HTTP transport.

Name Your Extension

Enter a name: stackone (or any name you prefer).

Enter Server URL

Paste the URL from the dashboard:

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

Enable Extension

When asked if you want to enable the extension, select “Yes”.

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:

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.

Multiple accounts

Add separate entries for each account:

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

Advanced: manual API key setup

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

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:

echo -n "<stackone_api_key>:" | base64

Using environment variables:

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 for details.

Verify installation

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

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:

Open Goose Desktop
Go to Settings → Extensions
Your StackOne extension should appear in the list
Toggle to enable/disable as needed

Troubleshooting

Extension not loading

Symptoms: StackOne tools don’t appear when asked “what tools do you have?”

Verify config file location: goose info -v
Check YAML syntax (indentation matters)
Ensure the extension is marked enabled: true
Restart Goose after config changes
Check logs: goose logs

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:

Verify base64 encoding includes the trailing colon: echo -n "your_api_key:" | base64
Confirm the account ID matches your linked account
Check the API key is valid in StackOne Dashboard

Connection timeout

Increase the timeout in your config:

timeout: 600  # 10 minutes

No tools available

Verify you have active integrations in the StackOne Dashboard
Check that actions are enabled in your integration config
Review StackOne Playground to see expected tools

YAML configuration errors

Validate YAML syntax at https://www.yamllint.com/
Check indentation (use spaces, not tabs)
Ensure quotes around header values
Run: goose info -v to see config parsing errors

Handling large tool catalogs

If the connector exposes many actions, add the tool-mode=search_execute query parameter to the MCP URL in your config. The client then registers just two tools — search + execute — and the agent discovers actions at runtime, so the context footprint stays flat however large the catalog:

https://api.stackone.com/mcp?tool-mode=search_execute

For a token URL, append it as an extra parameter: https://api.stackone.com/mcp?token=<session_token>&tool-mode=search_execute. See 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.

Search & Execute

Reduce context and save tokens.

Data Sync

Reduce latency and enable semantic search.

Defender

Block prompt injections before they reach your agent.

​Overview

​Prerequisites

​Get your MCP URL

​Setup methods

​Method 1: interactive configuration (recommended)

​Method 2: manual YAML configuration

​Advanced: manual API key setup

​Verify installation

​Desktop application

​Troubleshooting

​Handling large tool catalogs

​Optimize and secure

Search & Execute

Data Sync

Defender

Overview

Prerequisites

Get your MCP URL

Setup methods

Method 1: interactive configuration (recommended)

Method 2: manual YAML configuration

Advanced: manual API key setup

Verify installation

Desktop application

Troubleshooting

Handling large tool catalogs

Optimize and secure