MCP Client Sign-In¶

An MCP client signs in to QIE with OAuth 2.1, the same way it signs in to any other MCP server. The client first registers itself with QIE, then sends the person to the QIE console to sign in and approve it, and finally exchanges the approval for tokens. QIE is its own authorization server: the sign-in, the approval and the tokens all come from the QIE console.

This page describes each step from the client's side and from the person's side.

Client registration¶

A client that has never connected to this QIE registers itself first. It sends its name and the addresses it can be returned to after sign-in, and QIE answers with a client id. Registration needs no account and no administrator: any client that can reach the console can register, and nothing it registers can reach QIE until a person signs in and approves it.

QIE registers public clients only. A public client is one, such as a desktop application, that cannot keep a secret, so QIE issues no client secret and relies on PKCE to tie each sign-in to the client that started it. A request that asks for a client secret is refused.

Return addresses¶

After sign-in, the console sends the person's browser back to the client with an authorization code. QIE only ever sends that code to the computer the client runs on, so the only return addresses it accepts are http://127.0.0.1, http://[::1] and http://localhost, on any port.

A client may list up to five return addresses. QIE keeps the ones on the computer the client runs on and drops the rest, and its answer lists the addresses it kept. A registration is refused only when none is left. A client that lists both a web address and a localhost address can therefore still sign in through localhost.

What QIE stores¶

QIE stores the client's name, cut to 64 characters, its return addresses, the address the request came from, and the version details it sends. A client's name is its own description, and QIE does not check it. The client's web address and logo address are stored but never shown.

A registration that nobody approves within a day is deleted by the nightly cleanup, so a client that registers and never signs in leaves nothing behind.

Limits and refusals¶

One address can register Registrations per Address per Hour clients each hour, 10 by default (see MCP Settings). Further registrations from that address are refused with HTTP 429 and a Retry-After header that says when the hour ends. The first refusal in the hour writes an audit entry and raises the abuse alert described in Alerts.

Behind a reverse proxy, QIE counts registrations against the client's own address only when Proxy Hops is set (see User Authentication). Otherwise every client behind the proxy shares the proxy's address and one limit.

Every registration and every refused registration writes an audit entry, CLIENT_REGISTERED or CLIENT_REGISTRATION_REJECTED (see MCP Audit Log).

Client metadata documents¶

Some clients do not register. Instead, their client id is an HTTPS address, and the document at that address describes the client: its name and its return addresses. QIE fetches such a document only from a host an administrator has listed in Metadata Document Hosts on the Model Context Protocol (MCP) page. While that list is empty, QIE fetches no document, and clients register as described above.

Each line of Metadata Document Hosts holds one host name, such as claude.ai for Claude Code or chatgpt.com for Codex. A host name on its own allows that host on port 443 only; add the port, as in metadata.example.com:8443, when the documents are published on another port.

QIE fetches a document over HTTPS and checks the server's certificate against the Java runtime's own list of trusted certificate authorities, whatever the console's own certificate settings are. It does not follow redirects, reads at most 16 KB, and gives up after 5 seconds. The document must be a JSON object whose client_id is exactly the address it was fetched from, and it must list at least one return address. QIE refuses a document that fails any of these checks.

QIE keeps a fetched document as long as the server's Cache-Control header allows, up to 24 hours, and for one hour when the header gives no lifetime. A document marked no-store or no-cache is fetched again every time it is needed.

Every fetch writes an audit entry, CLIENT_METADATA_FETCHED or CLIENT_METADATA_REJECTED, naming the document's address, its host and why it was refused.

Signing in and approving the client¶

When a client connects, it opens the person's browser at the console's authorization address. QIE first checks the request: the console must be reached over HTTPS, the client must be registered or described by a metadata document, and the return address must be one the client listed. A request that fails one of these checks gets a short page that says why, and nothing is sent back to the client. QIE also checks that the client uses PKCE and asks only for MCP scopes; when it does not, QIE sends the error back to the client instead.

A person who is not signed in to the console goes to the console login page first, signs in as usual (with a local, LDAP or OIDC account, and two-factor authentication where it is on), and then comes back to the request.

One address can open the authorization address Token Requests per Address per Minute times each minute, 30 by default, counted apart from its token requests. A sign-in that starts at the login page opens it twice. Further requests from that address get a short page that says to try again later, before QIE checks anything else, and the first refusal in a minute writes an audit entry and raises the abuse alert.

The approval page¶

The approval page shows:

Client: the name the client gave itself, labeled as supplied by the client. QIE does not check this name, so approve only a client you started yourself.
Return Address: where the approval goes, always an address on the person's own computer.
Access: what the client may do, from Read only, Read and manage, no configuration changes or Full access: change configuration as you can in the console. Read only is selected whatever the client asked for, and the page says what it asked for. The access chosen is a ceiling: the client can never do more than the person could do in the console.
Do not keep me signed in: for shared computers, described below.

Approve sends the client an authorization code, which it exchanges for its tokens. Decline tells the client that access was refused. Either way, the page shows the result and then returns the browser to the client.

An approval page lasts 10 minutes and can be answered once. A page answered late, or opened again from the browser history, says it expired; start the connection from the client again. The page refuses to show inside another page, so another site cannot hide it under its own content.

Approving a registered client also keeps its registration: it no longer lapses after a day.

Every answer writes an audit entry, CONSENT_GRANTED or CONSENT_DENIED, with the access the client asked for, the access granted and the return address. Every refused request writes AUTHORIZATION_REFUSED with the reason.

Shared computers¶

On a computer other people use, check Do not keep me signed in. The client then gets no refresh token: when its access expires, it asks the person to approve it again. If the person signed in to the console only for this approval, the console also signs them out when they answer, whether they approve or decline.

Tokens¶

The client exchanges the authorization code for its tokens at the console's token address. A code works once, within 60 seconds, and only for the client it was issued to, with the return address and PKCE verifier of the request the person approved. A code presented a second time is treated as stolen: QIE revokes every token issued from it, writes a CODE_REUSE_DETECTED audit entry and raises the token replay alert described in Alerts.

QIE stores no token, only a fingerprint of it, so a copy of the database cannot be used to call the MCP server.

Access tokens¶

An access token lets the client call the MCP server for Access Token Lifetime (seconds), one hour by default (see MCP Settings). It is valid only for the MCP server's Resource URL: changing that setting retires every token, and every client must be approved again.

Refresh tokens¶

While Issue refresh tokens is on, the client also gets a refresh token, unless the person chose Do not keep me signed in. With it, the client gets a new access token when the old one expires, without asking the person again. Each use returns a new refresh token and spends the old one. A refresh token used a second time means two copies exist, so QIE revokes every token of that sign-in, writes a REFRESH_REUSE_DETECTED audit entry and raises the token replay alert; the person approves the client again.

A client may ask for a narrower scope when it renews its token, and later ask again for any scope up to the one the person approved, never wider.

A sign-in lasts at most Local User Refresh Lifetime (days) for a user whose password QIE checks, 30 days by default, and LDAP and OIDC User Refresh Lifetime (days) for a user checked by a directory or an OIDC provider, 1 day by default. Renewing a token never extends a sign-in. The directory lifetime is shorter because QIE cannot ask the directory again when a client renews its token.

A client can renew with the access it was granted or with less, never with more.

When a client presents a code or renews a token, QIE checks the account as the console does at sign-in. A user who is disabled, locked, holds a temporary password or whose password has expired is refused with the console's own message, for example "Password Expired. Sign in to the QIE console, change your password, then authorize again."

Two facts follow from tokens living apart from the console session:

Signing out of the console does not end a client's tokens. Revoke them on the Model Context Protocol (MCP) page instead.
A refresh token renews access without two-factor authentication for as long as it lasts. Turn Issue refresh tokens off, or shorten the refresh lifetimes, where every sign-in must pass two-factor authentication.

Limits¶

One address can make Token Requests per Address per Minute token requests, 30 by default. Further requests are refused with HTTP 429 and a Retry-After header, and the first refusal in a minute writes an audit entry and raises the abuse alert.

Every token issued writes TOKEN_ISSUED or TOKEN_REFRESHED, and every refusal TOKEN_REQUEST_REJECTED with the reason, such as an expired code or a verifier that does not match.

Revocation¶

Tokens end before their time in any of these ways:

A client revokes its own token at the console's revocation address, for example when its user signs out of it. Revoking a refresh token ends the whole sign-in; revoking an access token ends that token only.
An administrator revokes a client, one sign-in, or every sign-in on the Model Context Protocol (MCP) page (see Model Context Protocol (MCP)).
Disabling or deleting a user, in the console, by a configuration import or through the Management API, revokes all of that user's tokens. So do a lockout after too many failed sign-ins and a change of the user's password.

A revoked token is refused at once on every node, because every node checks tokens against the same database. Every revocation writes an audit entry naming what caused it, such as administrator, password or revoke_all.

Requests QIE refuses¶

QIE refuses to authorize MCP access through the QIE Hub, and from the QIE server itself. A request that the Hub forwarded, or one that arrives from the server's own address, is refused with HTTP 403, a warning in the engine log and an audit entry. A reverse proxy that runs on the QIE server must therefore forward to the server's network address rather than to 127.0.0.1 or localhost (see Deploying the MCP Server). To work at engines through the Hub, a person signs their AI assistant in at the Hub's own MCP server instead (see The MCP Server on a Hub).

While the MCP server is off, none of the sign-in addresses exists: each answers HTTP 404.