Goose CLI & Desktop

Overview

Goose 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).

A StackOne project you are a member of.
A connector profile in the project for each provider the client should reach, with the actions you want exposed enabled.
(Optional) A linked account for each provider. Accounts can also be linked during the consent flow.

Setup

Interactive configuration

Run the configuration wizard:

goose configure

Select 'Add Extension'

When prompted, choose Add Extension from the menu.

Choose extension type

Select Remote Extension (Streamable HTTP).

Name your extension

Enter stackone (or any name you prefer).

Enter the server URL

Paste https://mcp.stackone.com/mcp.

Approve the browser prompt

Goose opens StackOne in your browser.Sign in, pick the project and the linked accounts the connector should reach, then Authorize.

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: 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:

goose session

Then ask:

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.

Connecting with a session token instead

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. For a comparison of each connection method, see Choosing a connection method.From the StackOne dashboard, go to Connectors, open a connector, then click Use in Agent.

Pick a linked account.
Set the expiry (one year by default).
Select HTTPS MCP and copy the URL. It should be in the format of:
https://api.stackone.com/mcp?token={session_token}

This URL covers one linked account, and anyone holding it has that access until it expires, so treat it like a password.To enable Advanced Tool Search, add the tool-mode query parameter to the URL:

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:

extensions:
  stackone:
    name: stackone
    type: streamable_http
    url: https://api.stackone.com/mcp?token=<session_token>
    enabled: true
    timeout: 300

Multiple accounts

Add separate entries for each account:

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

Alternative: manual API key setup

To authenticate with your API key and account ID directly:

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:

echo -n "<stackone_api_key>:" | base64

Environment variables work too:

headers:
  Authorization: "Basic ${STACKONE_AUTH_TOKEN}"
  x-account-id: "${STACKONE_ACCOUNT_ID}"

See Authentication & Security for details.

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 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 with Use in Agent on the connector 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

Confirm you approved at least one account on the consent screen
Check that actions are enabled on the account’s connector profile
Review StackOne Playground to see expected tools

YAML configuration errors

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

Optimize and secure

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

Advanced Tool Search

Reduce context and save tokens.

Deep Query

Search synced records for a fraction of the tokens.

Defender

Block prompt injections before they reach your agent.

​Overview

​Prerequisites

​Setup

​Interactive configuration

​Manual YAML configuration

​Verify installation

​Desktop application

​Troubleshooting

​Optimize and secure

Advanced Tool Search

Deep Query

Defender

Overview

Prerequisites

Setup

Interactive configuration

Manual YAML configuration

Verify installation

Desktop application

Troubleshooting

Optimize and secure