ADR-019: The server is given a credential; acquiring one is a separate concern¶
mm-mcp acts as one Mattermost identity, with one of three credentials: a personal access token, a bot account's token, or the session token Mattermost issues when a person logs in, which its web app keeps in the MMAUTHTOKEN cookie. All three are sent the same way, as a bearer token, and the live suite proves each of them works. They differ in how they are obtained and how long they live: an access token lasts until it is revoked, a session expires on the server's schedule.
The server is given its credential and never obtains one. It reads MM_URL and MM_TOKEN from its environment, which an MCP client sets in the server's env block. No flag, argument or tool takes a credential, because a flag is visible in the process list and in the client's configuration of arguments, and a tool's arguments pass through the model. Obtaining a credential is a separate command, mm-mcp login, which stores it where the server finds it: the operating system's credential store, through go-keyring, which is the Windows Credential Manager, the macOS keychain, or the Secret Service of a Linux desktop. A token is stored per server, under its address, as the service mm-mcp. mm-mcp serve uses the stored token for MM_URL only when MM_TOKEN is not set, so the environment still decides, and a refused stored session tells the person to log in again. mm-mcp logout ends the session at Mattermost and forgets it.
mm-mcp login reads how the server signs people in before it opens anything, from what any server tells anyone: its client settings at /api/v4/config/client?format=old, and its OAuth authorization server metadata at /.well-known/oauth-authorization-server. Where the server offers OAuth, that is the only way it tries (ADR-034); otherwise it tries, in order, what the server allows. --with picks any one:
- OAuth in the person's own browser (RFC 8252), where the server's OAuth service is on and either lets a client register itself (RFC 7591) or has a public app an administrator registered for mm-mcp, given with
--client-id. mm-mcp listens on127.0.0.1, opens the authorization page in the default browser, whichever it is, with the person's everyday profile, and exchanges the code Mattermost sends back there, with a PKCE verifier, for a token. Nothing reads a cookie and no browser is driven. A client mm-mcp registered is stored, under the servicemm-mcp-oauth-client, and logged in as again, so a person registers once per server. - A browser window of mm-mcp's own, for single sign-on without OAuth. mm-mcp starts the first browser that lets itself be watched: an installed Chrome, Edge, Firefox or Chromium, then the Chromium Playwright downloads, which a company's browser policies do not reach, or the one
--browsernames. It gives the browser a profile of its own in a temporary directory, which it deletes afterwards, so nothing of the everyday browser is read, and remote control on a port of the system's choosing: the DevTools protocol for a Chromium, WebDriver BiDi for Firefox. Chrome refuses remote debugging on a person's everyday profile, so the separate profile is the only clean way in. The window opens the login page; the person logs in as they always do, second factor included; mm-mcp reads the window's cookies, HttpOnly ones included, until Mattermost sets MMAUTHTOKEN for the server's host, and closes it. A browser that opens no remote port within twenty seconds, as a policy forbidding remote debugging makes it, or that a snap or a Flatpak confines, is named, and the next one tried. A Chromium the system refuses its sandbox, as Ubuntu 24.04 refuses every browser it has no AppArmor profile for, starts again without it, as Playwright starts its Chromium, and the person is told; the window shows only the login page and closes once they have logged in. - The password, in the terminal, where the server keeps passwords: a login, the password, and the second factor's code when the account has one, through Mattermost's login API. The password is used once and kept nowhere; an account made through single sign-on is told it has none.
- A token the person pastes: a personal access token, a bot's, or the MMAUTHTOKEN cookie copied from their browser.
Whichever way, mm-mcp checks the token with Mattermost before it keeps it, and says, when nothing worked, what does: Playwright's Chromium, a token, or what to ask the administrator. The live suite logs in every way, on both supported releases, with every browser on the machine it runs on, headless, doing from the page what the person would; the browser tests drive each kind of browser on Linux, Windows and macOS (ADR-009).
Session login exists because many organisations disable personal access tokens and do not hand out bots, and a person on such a server has no other way to give an agent their access. A session token carries everything the person can do, so the safety rules for writes (ADR-021) apply to it as to any credential. An agent may run mm-mcp login for the person, but a token never passes through the model: the person types or pipes it into the command.
When adding a way to obtain or store a credential, keep it out of the serving path: the server must start and work from the environment alone. Never log a credential, never put one in an error message, and never return one from a tool. Keep a credential out of what a type prints, as config.Config's String and GoString do.
Not chosen¶
- A login flow inside the MCP server: A stdio server has no terminal and no browser of its own, and a server that can obtain credentials is a larger thing to trust than one that is handed one.
- Mattermost OAuth as the only way in: It needs an administrator to turn on the OAuth service and either let clients register themselves or register one, which is exactly what many people who need session login cannot get.
- Username and password in the configuration: It fails under single sign-on and multi-factor authentication, and stores the one secret that unlocks everything. The terminal prompt uses the password once and keeps only the session.
- A file of our own for the stored token: The operating system's credential store is encrypted to the person's login and is where they look for, and revoke, what their programs keep; a file would be one more copy of a session that unlocks everything they can do.
- Drive the login page for the person: Every organisation's login differs, single sign-on and second factors included; mm-mcp watches the cookies and leaves the page to the person.
- Mattermost's mobile hand-off,
mmauth://: It needs a URL handler registered with the operating system, which macOS grants only an app bundle, and claims a scheme that belongs to Mattermost's mobile app; a localhost redirect through it needs an administrator to list the address, and puts the session token in the browser's history. - Safari as the browser window: Its WebDriver must be switched on by hand and blocks the person from using the page while it runs; OAuth reaches Safari instead.
- Reading the everyday browser's cookie store: It is encrypted to the browser, and on Windows bound to it; getting around that is what credential stealers do.