Goose

Goose uses a YAML config file with Bearer token auth. No OAuth — Bearer is the stable path for Goose in 2026 due to a known OAuth token persistence bug.

OVERVIEW

Goose is an open-source AI agent from Block (now under the AAIF at the Linux Foundation). It runs as a desktop app, CLI, or API and connects to MCP servers via ~/.config/goose/config.yaml. Unlike most editors, Goose uses YAML format — not JSON. OAuth support exists but has a known bug (issue #3545, still open as of 2026) where the OAuth flow re-runs every new session instead of reusing stored tokens. Bearer key auth is the recommended stable method.

CONFIG FILE LOCATION

~/.config/goose/config.yaml — YAML format, not JSON.

PREREQUISITES

Goose installed from https://goose-docs.ai or via `brew install goose` (macOS) / `pip install goose-ai` (Python).
A Zephex account at zephex.dev/signup.
A Zephex API key from your dashboard.

CONFIG

Paste the YAML exactly as shown. Goose reads MCP extensions from `~/.config/goose/config.yaml`, so keep the indentation intact and keep `type: streamable_http` with the underscore.

Replace `{{API_KEY}}` with your Zephex API key from the dashboard. Do not use OAuth with Goose — a known bug causes re-authentication every session.

~/.config/goose/config.yaml

extensions:  - name: zephex    type: streamable_http    uri: https://zephex.dev/mcp    enabled: true    timeout: 300    headers:      Authorization: "Bearer {{API_KEY}}"

OPTIONAL — ADD VIA CLI INTERACTIVE MODE INSTEAD

Instead of editing the YAML manually, you can add the same remote extension interactively from the Goose CLI.

terminal

goose configure→ Add Extension→ Remote Extension (Streamable HTTP)→ Name: zephex→ URI: https://zephex.dev/mcp→ Timeout: 300→ Add header: Authorization: Bearer YOUR_KEY

AUTH

Goose uses Bearer token auth via the config file. No browser OAuth flow needed.

Open or create ~/.config/goose/config.yaml.
Paste the config block above, replacing {{API_KEY}} with your actual Zephex key.
Save the file.
Start Goose: run `goose session` in your terminal or open the Goose desktop app.

VERIFY

Verify both the extension registration and a live Goose session before you rely on Zephex tools.

Run `goose info -v` — it should list "zephex" as a connected extension.
Start a session: `goose session`.
Ask: "what tools do you have?" — Goose should list all 10 Zephex tools.

COMMON ISSUES

YAML indentation errors

Goose's config is strict YAML. Use spaces, not tabs. The `headers` block must be indented correctly under the extension entry.

"extension not found" error

Confirm the file is at `~/.config/goose/config.yaml`, not `~/.goose/config.yaml`. The path matters.

OAuth re-auth every session

This is a known Goose bug. Switch to Bearer token auth in the config file instead. Do not use the OAuth flow.

Tools not appearing

Check that `timeout: 300` is set. A low timeout can cause the connection to drop before tools are loaded.

If the editor still does not connect, return to Quickstart or check Connection Issues.