How to Add a Remote MCP Server to Goose

How do I add a remote MCP server to Goose?

Goose is Block's open-source AI agent, available as a desktop app and a CLI, and usable with any model provider. In April 2026 the project moved to the Agentic AI Foundation (AAIF) at the Linux Foundation — Block still contributes, but governance and the repository now sit with the foundation, and the project's docs and code live at goose-docs.ai and github.com/aaif-goose/goose (the older block.github.io/goose address now redirects there).

Both Desktop and CLI ultimately write the same thing: an entry under extensions in ~/.config/goose/config.yaml with type: streamable_http and a uri pointing at the server. Goose's docs show uri for the address and also accept url; the detail that actually trips people up is the type, which must be streamable_http with an underscore.

Desktop: Add custom extension

1. Open the sidebar (top-left) and select Extensions
2. Click Add custom extension
3. Choose the Streamable HTTP connection type
4. Enter the server's URL
5. Set a timeout (in seconds) for tool responses, and add headers or environment variables if the server needs them
6. Click Add

CLI: goose configure

goose configure

Choose Add Extension, then Remote Extension (Streamable HTTP), and follow the prompts for URL, timeout, and any variables.

For a one-off session without touching the config file:

goose session --with-streamable-http-extension "https://mcp.example.com/mcp"

The flag can be repeated to add more than one remote extension to the same session.

The config file

Either route above writes to ~/.config/goose/config.yaml, which you can also edit by hand:

extensions:
  my-server:
    name: My Server
    type: streamable_http
    uri: https://mcp.example.com/mcp
    enabled: true
    timeout: 300

type must be streamable_http, with an underscore. Goose's docs use uri for the address and list url as accepted too.

For a server that expects a header, such as an API key:

extensions:
  my-server:
    type: streamable_http
    uri: https://mcp.example.com/mcp
    headers:
      Authorization: "Bearer ${MY_SERVER_API_KEY}"

Authorization

For a server that supports Dynamic Client Registration or Client ID Metadata Documents, Goose registers itself and opens the browser consent screen automatically — there's nothing to configure ahead of time.

For a server whose authorization server supports neither, and requires a client registered out of band, add the registered credentials to the extension entry:

extensions:
  my-server:
    type: streamable_http
    uri: https://mcp.example.com/mcp
    client_id: <YOUR_REGISTERED_CLIENT_ID>
    client_secret_key: MY_SERVER_OAUTH_SECRET
    scopes:
      - example.readonly

If the OAuth flow needs a fixed callback port, set GOOSE_OAUTH_CALLBACK_PORT.

goose:// deeplinks

Goose Desktop supports install-by-link for extensions. For a command-based (stdio) extension the format is:

goose://extension?cmd=<command>&arg=<argument>&id=<id>&name=<name>&description=<description>

For a remote Streamable HTTP server, the equivalent uses url plus type=streamable_http:

goose://extension?url=<encoded-url>&type=streamable_http&timeout=<secs>&id=<id>&name=<name>&description=<description>

All parameter values must be URL-encoded. Clicking the link opens Goose Desktop and prompts to install the extension — useful for sharing a working config rather than asking someone to retype a URL.

Common failures

• Server never connects. Confirm type: streamable_http (underscore, not hyphen), that the address matches what the server publishes exactly, and that the file is valid YAML.
• Auth loop or repeated prompts. Current builds can re-prompt for authorization each session on some servers — approve and continue. If it fails outright, check whether the server needs an out-of-band client_id rather than relying on automatic registration.
• Tools time out. Raise the timeout value (seconds) on the extension entry.
• Not sure what's failing. goose info -v shows detailed configuration, including enabled extensions; --debug on goose session or goose run gives more detail on a failing connection.

A worked example

With a real server — Tempreon, a hosted MCP server that gives your AI a persistent memory of how you work — the config looks like:

extensions:
  tempreon:
    enabled: true
    type: streamable_http
    name: Tempreon
    uri: https://api.tempreon.com/functions/v1/tempreon-mcp/mcp
    timeout: 300

Goose Desktop also accepts this one-click link, which opens the add-extension dialog pre-filled:

goose://extension?url=https%3A%2F%2Fapi.tempreon.com%2Ffunctions%2Fv1%2Ftempreon-mcp%2Fmcp&type=streamable_http&id=tempreon&name=Tempreon&description=Your%20memory%20layer%20across%20AI%20tools

Either way, Goose starts the browser OAuth automatically when the server asks for it. The account-holder walkthrough, alongside the other open-source clients, is in the open-source clients doc.