Skip to content
BuildBase

Let your users connect Goose to your app

Get your app's MCP server ready for Goose, give your users a goose:// install link or the configure steps, and let Goose register itself.

This page is part of Agent-ready apps: it covers what you do so that your own users can connect Goose to the app you built with BuildBase. Your app serves MCP with @buildbase/sdk, and each user signs in on your hosted sign-in page and approves Goose as themselves.

Note

Want to manage BuildBase itself from your AI? See Use BuildBase in Goose, in BuildBase in your AI tools.

The examples use https://app.example.com/api/mcp, the default path createAgentStack serves, and the name acme.

Before you share the URL

  1. Serve MCP over HTTPS at a URL your users' machines can reach.

  2. Choose how Goose gets a client in Set up agent access. Goose tries a client ID metadata document or dynamic client registration by itself, so turn on Let agents register themselves with a base client, and Let agents identify themselves by a metadata document if you want that path too.

  3. Check it the way a client does:

    npx buildbase agent doctor --url https://app.example.com/api/mcp

What your users do

One click. Give your users a goose:// link. Every value is URL-encoded:

goose://extension?url=https%3A%2F%2Fapp.example.com%2Fapi%2Fmcp&type=streamable_http&id=acme&name=Acme&description=Acme%20for%20your%20account&timeout=300

By hand, with the steps for your help page:

  1. Run goose configure, choose Add Extension, then Remote Extension (Streamable HTTP).
  2. Enter acme and https://app.example.com/api/mcp.
  3. In Goose Desktop instead: Settings > Extensions > Add custom extension, with the Streamable HTTP type.

Goose then opens your sign-in page in the browser.

What your users see

  • Your sign-in page and consent screen, naming the client as it registered itself (or as its metadata document names it).
  • A malware scan of the extension before Goose turns it on.
  • Your tools' annotations. Mark read tools readOnlyHint: true and changes destructiveHint as they are, so a client can treat them differently.

When Goose connects, your user approves it on your consent screen. Here it is for an agent that registered itself:

Your app's consent screen for an agent that registered itself, here Notes Helper: a warning that the app gave itself its name and nobody has checked it, what it may do as the person, the permissions it asked for by name, and Allow access and Deny ringed

If something goes wrong

What your user seesWhyWhat to do
The install link does nothingA value in the link is not URL-encodedEncode every parameter, the URL most of all
Registration fails before your sign-in pageNeither self-registration nor metadata documents is onTurn one on in agent access
The sign-in fails at the redirectYour user's machine has the callback port in useThey set GOOSE_OAUTH_CALLBACK_PORT to a free port
Long calls time outThe extension's timeout is shorter than your tool takesRaise timeout in the link, or tell users to raise it

Related

Frequently asked questions

How does Goose get a client on my app?
Goose tries a client ID metadata document or dynamic client registration on its own, or takes a client_id you give it. Turn on Let agents register themselves, or metadata documents, and it needs nothing from you per user.
Can I give my users a one-click install?
Yes. Goose takes a goose://extension link with your URL, the streamable_http type, an id, a name, a description and a timeout, each URL-encoded.
Does Goose scan my server?
Goose's docs say extensions are scanned for malware before they are turned on. Your server is called normally after that.