Mailbox MCP
Connect a mailbox
All documentation
Connect a mailbox Client not listed? Ask us
On this page

Set-up documentation

Connect your mailbox to Goose

Goose takes YAML, not JSON. The block is extensions, the URL key is uri and the transport is streamable_http with an underscore. Three traps in four lines.

Time About 3 minutes
Where goose configure, Add Extension, Remote Extension
It needs URL and an access token
Top-level key extensions
URL key uri

Four things that differ from everything else

If you have configured any other MCP client, put the snippet away. Goose departs from the rest on four separate counts inside one five-line block, and none of them fail loudly.

Everywhere else Goose
JSON YAML
mcpServers extensions
url uri
http or streamableHttp streamable_http, with an underscore

There is a fifth difference that is not a key name: the documentation moved. block.github.io/goose now returns a 404 and the current documentation is at goose-docs.ai. Search results have not all caught up.

The configuration

This is the one page in this section where we cannot hand you a finished block, and it is worth saying why rather than filling the gap in.

Goose's documented remote extension carries a client_id and a client_secret_key, which is the shape of a server where somebody registered an application in advance. This server issues its client credentials on the fly instead, so those two fields have nothing to put in them. Goose's page documents no header block for a remote extension either, so where an access token goes, if it goes anywhere, is not something its documentation answers. Every YAML snippet you will find elsewhere that puts an Authorization header in here is somebody's guess, and we are not going to add another one.

What we can give you is the shape everything except the credential takes, because all four of these fields are in Goose's own example:

~/.config/goose/config.yaml YAML, not JSON. Credential handling: see below 
extensions:
  work-mail:
    name: Work mail
    type: streamable_http
    uri: https://mcp.mailbox-mcp.com/db/mcp/YOUR-MAILBOX-KEY
    enabled: true
    timeout: 300

timeout is in seconds and Goose's own example uses 300. A mailbox search across a large account is one of the slower things this server does, so leaving it generous is sensible; the default is lower.

So use the configure command instead

Run goose configure, let it write the entry, and then read what it produced. That file is the authority for the version you actually have, in a way no documentation page can be for a tool that has moved its credential handling between releases. If it prompts you for a token, create one in the control panel; if it offers to sign you in, take that instead and you will not have a credential to look after at all.

If you get it working, tell us which field the credential went in and this page will print the finished block with your name on the correction.

Or use goose configure

The route that does not require you to be right about the file format:

Terminal Interactive 
goose configure

Choose Add Extension, then Remote Extension (Streamable HTTP), and give it the connector URL. There is also a one-session form, goose session --with-streamable-http-extension, followed by the URL, which attaches the server for that session only and leaves your configuration untouched.

One caveat on the menu wording: older copies of the Goose documentation list "Remote Extension (SSE)" and "Remote Extension (Streaming HTTP)" alongside each other. The current page lists only Streamable HTTP. If your installation offers an SSE option, it is not the one you want.

Check that it worked

Try this first

Go through my unread mail and tell me which messages are waiting on me rather than on somebody else.

Nothing is marked read by asking, which matters more in an agent than in a chat client: a triage pass over a hundred messages leaves every one of them exactly as unread as it was.

The free tier is 5 MCP calls a day on any mailbox, with no card. An agent gets through those quickly, so the Pro ceiling is the realistic one here.

Connect a mailbox Sign in

Where to go next

The tool reference is the page to read next for an agent rather than a chat client: it marks which tools are read-only, which is what you need before you let anything run unattended. Pricing states the daily ceiling, which an agent reaches far sooner than a person does.

What we could not confirm
  • Whether Goose can register a client dynamically. Its documented YAML carries a pre-registered client_id and a secret key, which is why this page uses a token.
  • The Windows path for config.yaml.

Read 30 August 2026 Every value on this page came off Goose documentation: using extensions on that day. The old block.github.io/goose path 404s. If it has changed since, tell us and we will read it again.

By Mark McNeece, Founder Published Last reviewed Editorial standards