Logging in¶
Where your Mattermost lets you make a personal access token, that token is the
simplest way in: mm-mcp login --with paste keeps it in your system's
credential store (Installation). Many
organisations switch those tokens off. An administrator can open Mattermost's
OAuth instead, the way in mm-mcp prefers
(For administrators); until then, log in once with your
own account.
Step by step¶
- Install mm-mcp with a package manager (Installation).
-
In a terminal, run
with the address you open Mattermost at. One of two things happens:
- Your browser asks you to approve mm-mcp. Approve it, and close the tab.
- A browser window opens at your sign-in page. Log in as you always do, second factor included. The window closes by itself.
Where your server keeps passwords, mm-mcp may ask for yours in the terminal instead. 3. It says
Logged in to https://chat.example.com as @you. mm-mcp keeps the session in your system's credential store: the Windows Credential Manager, your macOS keychain, or your Linux desktop's Secret Service. 4. In your AI app, set only the address,MM_URL, and leave the token empty. Restart the app, so it starts mm-mcp again. 5. Ask it who you are in Mattermost. It answers with your username.
When step 2 fails, mm-mcp ends with what it tried and why each failed, and what
to do: most often, install Playwright's Chromium,
or ask your administrator for a change that
lets everyone in through their own browser.
mm-mcp doctor --url https://chat.example.com checks the login at any time
(below). When Mattermost ends the session,
run mm-mcp login again; mm-mcp logout ends it yourself.
How mm-mcp logs you in¶
Before it opens anything, mm-mcp reads how your server signs people in, which any server says to anyone: its login page's settings, and whether it is an OAuth authorization server. From that it makes a plan, a list of ways to log in, and tries them one after the other until one gives it a session Mattermost accepts.
flowchart TD
start(["mm-mcp login"]) --> discover["Read how the server<br>signs people in"]
discover -->|"could not read it"| guess["Warn, and assume<br>single sign-on"]
discover --> plan["Plan the ways to try,<br>or take the one<br>--with names"]
guess --> plan
plan --> next{"A way left<br>to try?"}
next --> try["Try the next way"]
try -->|a token| check{"Does Mattermost<br>say whose it is?"}
check -->|yes| store["Keep it in the<br>credential store"]
store --> done(["Logged in as @you"])
store -->|"no credential<br>store here"| env(["Put the token<br>in MM_TOKEN instead"])
try -. "failed, and says why" .-> next
check -. "no" .-> next
try -->|"ten minutes passed,<br>or Ctrl+C"| advice
next -->|"none left"| advice(["Sum up what failed,<br>and what works instead"])
Every way that fails says why before the next is tried. When none is left, mm-mcp sums up each way it tried and why it failed, and what would work for your server: Playwright's Chromium, a token, or the change to ask your administrator for. The whole login waits at most ten minutes.
mm-mcp found no way to log in to https://chat.example.com that worked:
- browser window: no browser would let mm-mcp watch the login: Chrome opened no DevTools port within 20s; …
- pasted token: no token was given
What works from here:
- A browser window: install Playwright's Chromium, a browser of its own in your user folder, with
npx playwright install chromium
and run mm-mcp login again.
…
The order it tries them in¶
| What your server offers | What mm-mcp tries, in order |
|---|---|
| Single sign-on, perhaps beside passwords | a browser window, then your password if the server keeps passwords or uses LDAP, then a pasted token |
| Passwords or LDAP, without single sign-on | your password, then a browser window, then a pasted token |
| Neither that mm-mcp can see, or it could not read the server | a browser window, then a pasted token |
When the server offers OAuth, it is the only way tried: its OAuth service is
on, and mm-mcp has a client to log in as, because the server lets it register
one itself, you gave one with --client-id, or an earlier login remembered
one. An administrator who opened that way in chose it, so mm-mcp does not fall
back to the others on its own. --with oauth, --with window,
--with password or --with paste tries only the way it names.
The four ways¶
- OAuth, in your own browser. mm-mcp opens Mattermost's authorization
page in your default browser, whichever it is, Safari included, with your
everyday profile. You are usually logged in there already, so you only
approve mm-mcp. Mattermost sends your browser back to a page mm-mcp serves on
127.0.0.1with a one-time code, which mm-mcp exchanges for a session. Nothing reads your browser's cookies (below). This is Mattermost's own OAuth service, Mattermost granting mm-mcp access, not the sign-on your organisation logs in with, such as Okta or Entra ID; it works beside it. - A browser window of mm-mcp's own, for single sign-on: SAML, Entra ID, OpenID Connect, GitLab, Google. mm-mcp starts a Chrome, Edge, Chromium or Firefox installed on your machine, or the Chromium Playwright downloads, with a profile of its own that it deletes afterwards, at your server's login page. You log in as you always do, second factor included; mm-mcp watches the window's cookies until Mattermost sets its session cookie, and closes it. Because the profile is new, you log in fresh there, even when your everyday browser is logged in (below).
- Your password, in the terminal, where your server keeps passwords or signs people in with LDAP: an email address or username, the password, and your authenticator's code when your account has a second factor. An account made through single sign-on has no password in Mattermost, and is told so.
- A token you paste, as the last resort: a personal access token, a bot's
token, or the value of the
MMAUTHTOKENcookie your browser holds for the server, from its developer tools while you are logged in (Application or Storage, then Cookies). The terminal does not show what you type, and a token piped into the command is read as it is.
Whatever way you log in, mm-mcp asks Mattermost whose the session is before it
keeps it, and says so: Logged in to https://chat.example.com as @you.
OAuth, step by step¶
mm-mcp logs in as a program on your machine does under OAuth (RFC 8252), with PKCE in place of a client secret, so a code another program catches on the way is of no use to it:
sequenceDiagram
autonumber
participant M as mm-mcp
participant B as Your browser
participant S as Mattermost
opt No client to log in as yet
M->>S: Register mm-mcp as a public client,<br>with a callback on 127.0.0.1
S-->>M: Its client id, remembered for the next login
end
Note over M: Listen on 127.0.0.1,<br>make a secret verifier
M->>B: Open the authorization page
B->>S: You approve mm-mcp, logged in as you already are
S-->>B: Back to 127.0.0.1/callback, with a one-time code
B->>M: The code
M->>S: The code and the verifier
S-->>M: A session token
The page on 127.0.0.1 says whether mm-mcp is logged in; you can close the tab
then. A callback that does not answer the login mm-mcp started is turned away.
The browser window¶
mm-mcp drives none of the login page itself: it only starts the browser, opens the page, and reads the browser's cookies, a Chromium's through its DevTools protocol and a Firefox's through WebDriver BiDi.
flowchart TD
find["Find the browsers"] --> next{"A browser<br>left?"}
next --> confined{"A snap or<br>a Flatpak?"}
confined -->|no| launch["Start it with a new profile,<br>at the server's login page"]
launch --> answer{"Can mm-mcp reach it<br>within twenty seconds?"}
answer -->|yes| wait["You log in; mm-mcp reads<br>the cookies twice a second"]
answer -->|"a Chromium refused<br>its sandbox"| bare["Start it again without<br>its sandbox, and say so"] --> wait
wait -->|"Mattermost set<br>MMAUTHTOKEN"| got(["Close the browser,<br>delete the profile"])
wait -->|"you closed<br>the window"| closed(["The next way<br>is tried"])
confined -. "yes: skip it" .-> next
answer -. "no: a policy forbids it,<br>or it exited" .-> next
next -->|"none left"| none(["No browser would let<br>mm-mcp watch the login:<br>the next way is tried"])
The browsers are the one --browser names, alone, or else every Chrome, Edge,
Firefox and Chromium installed, in that order, and then Playwright's Chromium,
newest first. On Windows and macOS, mm-mcp looks where each browser's installer
puts it; on Linux, for google-chrome, microsoft-edge, firefox and
chromium on your PATH. Playwright's Chromium is in your user folder, or
under PLAYWRIGHT_BROWSERS_PATH when you set it.
When the window will not open¶
A browser can refuse to be watched:
- A company policy that forbids remote debugging in Chrome or Edge. mm-mcp waits twenty seconds for the browser, names it, and tries the next one.
- A snap or a Flatpak browser on Linux, whose sandbox keeps it from using a profile of mm-mcp's.
On Ubuntu 24.04, a Chromium without an AppArmor profile, Playwright's included, is refused its own sandbox; mm-mcp then starts it without one, as Playwright does, and says so. The window shows only your login page and closes once you have logged in.
Playwright's Chromium is a separate browser installed in your user folder, not the Chrome or Edge your organisation manages. Check with your organisation before you use it there. Install it once, with Node.js:
and run mm-mcp login again: mm-mcp finds it on its own. --browser names any
other Chrome, Edge, Chromium or Firefox, by path or command.
Your organisation's single sign-on may also require a managed device or browser, as Entra ID's Conditional Access and Okta's device trust can. A fresh profile is then refused at the sign-on page itself, Playwright's included; OAuth in your own browser, or a pasted token, still works.
When the login fails¶
mm-mcp names what failed, before it tries the next way:
| It says | Which means | What to do |
|---|---|---|
warning: reading how … lets people sign in |
The server's login settings did not answer; mm-mcp assumes single sign-on | Check the address is the one you open Mattermost at |
… opened no DevTools port within 20s, or started no remote agent |
A company policy forbids watching that browser | Install Playwright's Chromium (above) |
… is installed as a snap or a Flatpak |
Its sandbox keeps out mm-mcp's profile | Install Playwright's Chromium, or name another browser with --browser |
no browser would let mm-mcp watch the login |
Every browser found refused | The same |
the browser was closed before the login finished |
The window closed before Mattermost set its session cookie | Run mm-mcp login again, and log in before you close it |
the server lets no OAuth client register itself, and no client id was given |
OAuth is on, but mm-mcp has no client to log in as | Ask your administrator for one of two changes |
listening for the OAuth callback on port … |
Another program holds the callback's port | Close it, or use --callback-port when the app's callback names another |
mm-mcp was not authorized |
You, or the server, refused mm-mcp on the authorization page | Approve it, or try --with window |
the account signs in through single sign-on and has no password |
Your account has no password in Mattermost | mm-mcp login --with window |
nothing could be read here |
The password or token prompt runs where nobody types, as in an AI agent's shell | Run mm-mcp login in a terminal of your own |
x509: certificate signed by unknown authority |
Your organisation signed the server's certificate itself | Set MM_MCP_CA_FILE to its authority's certificate, in this terminal too (Configuration) |
the token does not work |
Mattermost refused what the way obtained | The next way is tried; a pasted token may be mistyped or revoked |
… Set the token as MM_TOKEN in the MCP client's env block instead |
Your system has no credential store mm-mcp can use, as on a Linux without a desktop | Put the token in MM_TOKEN, from --with paste or a personal access token |
Where the session is kept, and when it ends¶
mm-mcp keeps one session per server, under the name mm-mcp, in the Windows
Credential Manager, your login keychain on macOS, or your desktop's Secret
Service on Linux, such as GNOME Keyring or KWallet. It also keeps, under
mm-mcp-oauth-client, the OAuth client it logged in as, which is no secret, so
the next login uses it again.
mm-mcp serve uses the stored session whenever MM_URL names that server and
MM_TOKEN is not set; a token in MM_TOKEN always goes first. A session ends
when Mattermost expires it, or when it is revoked, by you under Profile >
Security or by an administrator. How long a session lasts is your server's to
say: an administrator sets it under System Console > Environment > Session
Lengths, often to days or weeks. A personal access token or a bot's token you
pasted lasts until it is revoked. Once it ends, mm-mcp serve stops at start with
refused the session mm-mcp login stored; run mm-mcp login again, and restart
the MCP server.
mm-mcp logout forgets the stored login, and ends at Mattermost a session
mm-mcp made itself. A token you pasted it only forgets: a personal access token
lasts until you revoke it, and a pasted MMAUTHTOKEN is your browser's own
session, which ending it would log your browser out of.
When the tools still do not work¶
checks the login you stored and everything around it, and says what to fix:
whether a login is stored under that address in your credential store, whether
the store can be read at all, whether an MM_TOKEN hides the login, whether
the server can be reached and still accepts the session, and how
mm-mcp login would log you in. The most common causes:
MM_TOKENis still set in your MCP client's configuration. It wins over a stored login; remove it.- Another spelling of the address. A login is stored under the address you
logged in with:
httpis nothttps, and another host name for the same server is another entry. Log in with the addressMM_URLnames. - No credential store. On Linux, the Secret Service runs with your desktop
session; over SSH, in WSL or in a container there is none. Use a token in
MM_TOKENthere.
The command reads your terminal's environment, not your MCP client's. From
inside the client, ask the model to call the diagnose tool: it makes the same
checks with the client's own configuration, and says who decides on a write
and, where mm-mcp is set to ask, whether the client can show its question.
What to ask your administrator¶
One change on the server lets everyone log in through their own browser, in
one click: turning on dynamic client registration, or registering one OAuth app
for mm-mcp. Send your administrator For administrators,
which has the steps, and why letting agents in this way is the safer choice.
With a registered app, run mm-mcp login --client-id <id> once, with the id
your administrator gives you; mm-mcp remembers it for the server.
--callback-port uses another port, when the app's callback names one.
To see what your server offers, open
https://chat.example.com/.well-known/oauth-authorization-server: an error page
means its OAuth service is off; a JSON answer means it is on, and with a
registration_endpoint in it, mm-mcp can register itself.
With an AI agent¶
An agent can run mm-mcp login for you: OAuth and the browser window need
nothing typed, so you log in in the window or approve in your browser. Your
password and a pasted token are typed into a terminal, which an agent's shell is
not; there, mm-mcp says to run it in a terminal you can type in. Never paste a
token into the conversation: run mm-mcp login --with paste yourself and paste
it at the command's own prompt. When nothing works, mm-mcp ends with what it
tried and what to do next, which an agent can read to you.
For the agent:
- Give the login time. It waits up to ten minutes for the person, longer than a shell's usual timeout. Run it in the background, and tell the person first what will open; a timeout of exactly ten minutes can end it as it finishes.
- Check that it took with
mm-mcp doctor --url https://chat.example.com --json, which exits with status 1 when a check failed. - Restart the MCP client, or reconnect its server, after adding mm-mcp or changing its settings: a client reads both when it starts. On Windows, a shell started before mm-mcp was installed does not find it either.