Skip to content

ui: sign in to MCP servers with the browser (OAuth) - #63

Draft
allozaur wants to merge 2 commits into
allozaur/refactor/mcp-extensionfrom
allozaur/feat/mcp-oauth-login
Draft

allozaur wants to merge 2 commits into
allozaur/refactor/mcp-extensionfrom
allozaur/feat/mcp-oauth-login

Conversation

@allozaur

Copy link
Copy Markdown
Owner

Overview

MCP servers that support OAuth can be signed in to from Llama Chat with the browser, as on Notion, Linear or Hugging Face, while a token in the server's Authorization field keeps working as before.

Additional information

Beside the work-in-progress stack on the fork, based on allozaur/refactor/mcp-extension (#61), the MCP extension; like Model configuration beside the prompt library, it is not part of stack ggml-org#62. Its diff is only this layer. All of it is MCP extension code, in src/lib/extensions/mcp/.

It mirrors Hugging Face chat-ui's MCP OAuth where a static app can, and takes the browser-side approach of the earlier attempt on the fork by LPFchan (allozaur/feat/mcp-oauth), rebuilt on the MCP SDK v2 and the extension.

Known gaps:

  • No Client ID Metadata Document: the authorization server has to fetch it from a public HTTPS URL whose redirect URIs match, which an app served from localhost or a LAN address cannot offer. Servers that advertise one fall back to dynamic client registration.
  • An authorization server may refuse to register a plain-http redirect URI that is not loopback (a LAN or Tailscale address). Then the card asks for the client ID of an app registered by hand.
  • Tokens live in localStorage, readable by any script of the origin, as the rest of the app's data is. chat-ui keeps them on its server, encrypted.
  • Not tried against a public server: signing in creates an app registration there, which is for a person to do. Notion, Linear and Hugging Face advertise dynamic registration and send CORS headers on every endpoint; Sentry and Stripe need Use llama-server proxy. GitHub's MCP host could not be reached from the test machine.
  • The step-up to a wider scope on 403 insufficient_scope is left to the SDK's defaults, and a sign-in in one tab does not refresh what other tabs show until they hear the broadcast.
How it works
  • Who signs in, and when: a connection in the background never opens a page or registers anything. When the server answers 401 and publishes an authorization server, the connection stops with "Sign in to use this server" and the card offers Sign in with <authorization server>. A 401 with no authorization server says to add a token instead.
  • The flow: the MCP SDK's auth() runs discovery, dynamic client registration, PKCE (S256), the code exchange and refresh. An OAuthClientProvider keeps the client, tokens, verifier, discovery state and a random state per server and URL in one localStorage entry, apart from the settings, so a settings export never carries tokens. The resource asked for is the server's URL.
  • The trip to the authorization page: a popup, or this tab when the popup is blocked. The authorization server sends the browser back to the app's root with ?mcp_oauth=1. That page load checks the state, clears the code from the address bar, exchanges it and tells every tab on a BroadcastChannel; the UI is served cross-origin isolated, so a popup cannot reach its opener. A sign-in in this tab returns to the route it started from. The server then connects again with its token.
  • No registration on offer: the card asks for the client ID (and secret, if any) of an app the user registered with the authorization server, and shows the redirect URL to register it under. The secret only goes to the token endpoint.
  • Refresh and sign-out: an expired token refreshes on its own; a refused refresh brings the sign-in back. Sign out (and deleting the server) revokes the token where the authorization server allows it, closes the connection and keeps the client registration for the next sign-in.
  • Headers: an Authorization header set on the server wins: such a server is never offered a sign-in, as in chat-ui, where the two are exclusive.
  • Proxy: with Use llama-server proxy, the transport now keeps the real server URL and its fetch sends every request (MCP, discovery, registration, token, revocation) through /cors-proxy. Before, the transport was given the proxy URL, from which the SDK would have derived the resource and the discovery URLs.
  • Errors: the callback's error_description comes from the address bar and is not shown; the card says the sign-in was cancelled or refused, with the error code.
Testing
  • npm run check, prettier --check and eslint pass. 852 unit tests and 301 client tests pass. 295 of 296 story tests pass; ChatAttachmentsPreview › PdfConversionError times out in the full run and passes on its own, as on the layers below. The production build completes.
  • tests/unit/mcp-oauth.test.ts runs the whole flow against an in-process MCP server behind OAuth (protected resource and authorization server metadata, registration, an authorize step, a token endpoint that checks PKCE, revocation): a background connection stops without registering; sign-in registers and sends the popup to the authorization page with PKCE, state and resource; the callback signs in and the server connects with the token; refresh; a refused refresh; a denied sign-in; a forged state; a sign-in in this tab returning to its route; sign-out with revocation; a server URL change; the Authorization header winning; a 401 with no sign-in; the client ID fallback with a secret; and the whole flow through the CORS proxy, keeping the real resource.
  • The MCP server card story has a Sign-in state per step, with assertions.
  • In the browser, against a local OAuth-protected MCP server: add the server, see Sign in with 127.0.0.1:3911, sign in (the in-app browser opened it in the same tab), approve, back on the MCP page signed in with its tool; sign out (revoked on the server), sign in again (the same client registration reused). The same against a copy of that server sending no CORS headers, with Use llama-server proxy on, through a real llama-server.

Requirements

@github-actions github-actions Bot added the documentation Improvements or additions to documentation label Nov 16, 2026
@allozaur
allozaur force-pushed the allozaur/refactor/mcp-extension branch from d6d9c83 to d48911f Compare November 16, 2026 07:05
@allozaur
allozaur force-pushed the allozaur/feat/mcp-oauth-login branch from 38eb4d6 to 9a5978a Compare November 16, 2026 07:05
@allozaur
allozaur force-pushed the allozaur/refactor/mcp-extension branch from d48911f to 9374b2e Compare November 16, 2026 08:19
@allozaur
allozaur force-pushed the allozaur/feat/mcp-oauth-login branch 2 times, most recently from 47cf9ff to a4ce37f Compare November 16, 2026 09:24
@allozaur
allozaur force-pushed the allozaur/refactor/mcp-extension branch from 209f536 to 9ed55c6 Compare November 16, 2026 10:42
@allozaur
allozaur force-pushed the allozaur/feat/mcp-oauth-login branch 2 times, most recently from 7154839 to afd5c4c Compare November 16, 2026 11:28
@allozaur
allozaur force-pushed the allozaur/refactor/mcp-extension branch from 9ed55c6 to 91b08e6 Compare November 16, 2026 11:28
@allozaur
allozaur force-pushed the allozaur/feat/mcp-oauth-login branch from afd5c4c to 706ffcb Compare November 16, 2026 11:43
@allozaur
allozaur force-pushed the allozaur/refactor/mcp-extension branch from 91b08e6 to 180211b Compare November 16, 2026 11:43
@allozaur
allozaur force-pushed the allozaur/feat/mcp-oauth-login branch from 706ffcb to b0c434d Compare November 16, 2026 11:56
@allozaur
allozaur force-pushed the allozaur/refactor/mcp-extension branch from 180211b to 30d4ec9 Compare November 16, 2026 11:56
@allozaur
allozaur force-pushed the allozaur/feat/mcp-oauth-login branch from b0c434d to 1a7e565 Compare November 16, 2026 12:07
@allozaur
allozaur force-pushed the allozaur/refactor/mcp-extension branch 2 times, most recently from 08a82f3 to d59ef64 Compare November 16, 2026 12:13
@allozaur
allozaur force-pushed the allozaur/feat/mcp-oauth-login branch 2 times, most recently from 21d49bd to 67fb6a4 Compare November 16, 2026 12:17
@allozaur
allozaur force-pushed the allozaur/refactor/mcp-extension branch 2 times, most recently from 462e309 to 1a410e7 Compare November 16, 2026 13:09
@allozaur
allozaur force-pushed the allozaur/feat/mcp-oauth-login branch 2 times, most recently from 150c7ab to 76f1ec2 Compare November 16, 2026 13:44
@allozaur
allozaur force-pushed the allozaur/refactor/mcp-extension branch 2 times, most recently from 342f684 to a613dc3 Compare November 16, 2026 13:52
@allozaur
allozaur force-pushed the allozaur/feat/mcp-oauth-login branch from 76f1ec2 to 867ee0b Compare November 16, 2026 13:52
@allozaur
allozaur force-pushed the allozaur/feat/mcp-oauth-login branch from 867ee0b to fe02f27 Compare November 16, 2026 16:12
@allozaur
allozaur force-pushed the allozaur/refactor/mcp-extension branch from aed2e4b to ee4438f Compare November 16, 2026 16:50
@allozaur
allozaur force-pushed the allozaur/feat/mcp-oauth-login branch from fe02f27 to b850b3a Compare November 16, 2026 16:50
@allozaur
allozaur force-pushed the allozaur/feat/mcp-oauth-login branch from 45af8e6 to 635b508 Compare November 17, 2026 10:31
@allozaur
allozaur force-pushed the allozaur/refactor/mcp-extension branch from 7ba55eb to 8cee71a Compare November 17, 2026 11:16
@allozaur
allozaur force-pushed the allozaur/feat/mcp-oauth-login branch from 635b508 to 3624aaa Compare November 17, 2026 11:16
@allozaur
allozaur force-pushed the allozaur/refactor/mcp-extension branch from 8cee71a to 337b305 Compare November 17, 2026 11:20
@allozaur
allozaur force-pushed the allozaur/feat/mcp-oauth-login branch from 3624aaa to 05c0255 Compare November 17, 2026 11:20
@allozaur
allozaur force-pushed the allozaur/refactor/mcp-extension branch from 337b305 to dbe13ff Compare November 17, 2026 12:27
@allozaur
allozaur force-pushed the allozaur/feat/mcp-oauth-login branch from 05c0255 to 67a568e Compare November 17, 2026 12:27
@allozaur
allozaur force-pushed the allozaur/refactor/mcp-extension branch from dbe13ff to 7ccbcc7 Compare November 17, 2026 12:44
@allozaur
allozaur force-pushed the allozaur/feat/mcp-oauth-login branch from 67a568e to 3c20741 Compare November 17, 2026 12:44
@allozaur
allozaur force-pushed the allozaur/refactor/mcp-extension branch from 7ccbcc7 to ccd91a9 Compare November 17, 2026 13:05
@allozaur
allozaur force-pushed the allozaur/feat/mcp-oauth-login branch from 3c20741 to 39456ac Compare November 17, 2026 13:05
@allozaur
allozaur force-pushed the allozaur/refactor/mcp-extension branch from ccd91a9 to d802e84 Compare November 17, 2026 13:13
@allozaur
allozaur force-pushed the allozaur/feat/mcp-oauth-login branch 3 times, most recently from c937d8a to feecd08 Compare November 17, 2026 13:44
allozaur added a commit that referenced this pull request Nov 17, 2026
The tree is the integration's: develop is the stack's top plus the side branches.
@allozaur
allozaur force-pushed the allozaur/feat/mcp-oauth-login branch from feecd08 to 9fdf685 Compare November 17, 2026 15:28
@allozaur
allozaur force-pushed the allozaur/refactor/mcp-extension branch from 2274890 to 4646d3a Compare November 17, 2026 15:28
allozaur added a commit that referenced this pull request Nov 17, 2026
@allozaur
allozaur force-pushed the allozaur/feat/mcp-oauth-login branch from 9fdf685 to 8420216 Compare November 17, 2026 16:26
@allozaur
allozaur force-pushed the allozaur/refactor/mcp-extension branch from 681d0a0 to 60bc00e Compare November 17, 2026 16:42
@allozaur
allozaur force-pushed the allozaur/feat/mcp-oauth-login branch from 8420216 to bf7520e Compare November 17, 2026 16:45
allozaur added a commit that referenced this pull request Nov 17, 2026
@allozaur
allozaur force-pushed the allozaur/refactor/mcp-extension branch from 60bc00e to bdf5041 Compare November 17, 2026 17:16
@allozaur
allozaur force-pushed the allozaur/feat/mcp-oauth-login branch from bf7520e to 66e3372 Compare November 17, 2026 17:16
allozaur added a commit that referenced this pull request Nov 17, 2026
@allozaur
allozaur force-pushed the allozaur/feat/mcp-oauth-login branch from 66e3372 to 9fbcfb6 Compare November 17, 2026 17:20
@allozaur
allozaur force-pushed the allozaur/refactor/mcp-extension branch from bdf5041 to 8b0405e Compare November 17, 2026 17:20
An MCP server that answers 401 and publishes an OAuth authorization server
can now be signed in to, in the browser, with no server of our own: the MCP
SDK's auth() runs discovery, dynamic client registration, PKCE, the code
exchange and refresh, and an OAuthClientProvider here keeps the client, the
tokens, the verifier and the discovery state per server in localStorage,
apart from the settings so tokens never travel with a settings export.

A connection in the background never opens a page or registers a client: it
stops with "sign in to use this server", and a server whose 401 offers no
sign-in says to add a token instead. A sign-in the user starts opens the
authorization page in a popup (or this tab when it is blocked); the page
comes back to the app's root, which exchanges the code, checks the state,
and tells every tab on a BroadcastChannel, since the cross-origin isolated
UI cuts the popup off from its opener. The server then connects again.
Sign-out revokes the token where the authorization server allows it.

An Authorization header the user set wins: such a server is never offered a
sign-in. Through llama-server's CORS proxy the transport now keeps the real
server URL and the fetch sends every request through the proxy, so the
resource a token is asked for and the discovery URLs are the server's own.

Mirrors Hugging Face chat-ui's MCP OAuth where a static app can, and builds
on the earlier attempt on the fork by LPFchan.

Assisted-by: Claude (Opus 5.5 Medium)
A server that needs a sign-in shows "Sign in with <authorization server>"
on its card instead of the error its connection ended with. While the
authorization page is open the card waits, with a way to give up; a server
whose authorization server registers no apps asks for the client ID (and
secret, if any) of an app the user registered there, with the redirect URL
to register it under; a signed-in server says so and offers Sign out.

Signing out, and deleting a server, revoke its tokens where the
authorization server allows it, close its connection and take its tools
out, so the card is back to the sign-in at once.

The MCP server card story has a Sign-in state for each of these.

Assisted-by: Claude (Opus 5.5 Medium)

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation server/ui

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant