Deploying the MCP Server¶
The MCP server has two parts, and a deployment has to reach both. Clients sign in through the QIE console, at the Issuer URL, and call tools on the MCP listener, at the Resource URL (see MCP Settings). Both addresses must be HTTPS addresses that the client's computer can reach.
The Usual Deployment¶
In the setup this page covers, QIE runs on a server, such as a virtual machine, and each person runs their AI client on their own workstation. A sign-in then works like this:
- The browser on the workstation opens the console at the Issuer URL, where the person signs in and approves the client.
- After approval, the browser hands the sign-in back to
localhost. That is the workstation, where the AI client waits for it, not the QIE server. - The AI client then reaches the server on two ports: the console port, to collect and renew its tokens, and the MCP port, to call tools.
So each workstation needs to reach the console port and the MCP port on the server, and nothing needs to reach the workstation.
Console addresses a reverse proxy must forward¶
A client finds out how to sign in by reading the console's authorization server metadata. For the default Issuer URL, https://<console>/qie, the document is at:
This address is at the root of the console's host, outside /qie. A reverse proxy that forwards only /qie/ to QIE must also forward this one address, or clients cannot find the sign-in endpoints.
The document lists the sign-in endpoints, all under the issuer:
| Endpoint | Address |
|---|---|
| Registration | <issuer>/oauth/register |
| Authorization | <issuer>/oauth/authorize |
| Token | <issuer>/oauth/token |
| Revocation | <issuer>/oauth/revoke |
When the Issuer URL is a proxy address with a different path, such as https://gateway.example.com/integration/qie, clients look for the document at https://gateway.example.com/.well-known/oauth-authorization-server/integration/qie. The proxy must send that address to QIE's /.well-known/oauth-authorization-server/qie, and send the endpoints under the issuer to the same endpoints under QIE's /qie.
The issuer in the document is exactly the Issuer URL setting, or its default when the setting is empty. Clients compare it character for character with the address they started from, so set it to the address clients use, including the proxy's host name.
A reverse proxy on the QIE server¶
QIE refuses to authorize MCP access for a request that comes from the QIE server itself (see MCP Client Sign-In). A reverse proxy that runs on the same server and forwards to 127.0.0.1 or localhost makes every request look as if it came from the server, so every sign-in is refused. Point such a proxy at the server's network address instead.
The listener's address¶
Clients reach the MCP listener at the Resource URL, and the listener answers only requests addressed to that host name and port (see MCP Listener). Choose a name every client can resolve, and issue the listener's certificate for that name.
Every node runs the listener on the MCP Port, so in a container deployment every node instance's container, and the service in front of the nodes, must expose that port. In a cluster, the Resource URL names the shared address in front of the nodes, never one node. A request that names a node's own host name is refused, so the nodes cannot be reached one by one.
A client keeps its MCP session in memory on the node that started it. A load balancer in front of the nodes must therefore send each client's requests to the same node for as long as the session lasts (sticky sessions); a request that reaches another node finds no session there and the client has to connect again.
The listener counts its per-address limits against the address that connected to it. Behind a load balancer that passes TLS through to the nodes, that is each client's own address. Behind one that ends TLS and connects to the nodes itself, every client shares the balancer's address, and with it one allowance of requests without a token.
Client addresses behind a proxy¶
The console limits client registrations and token requests per address. Behind a reverse proxy, set Proxy Hops to the number of proxies so that QIE counts each client's own address rather than the proxy's (see User Authentication). Proxy Hops applies to the console only; the MCP listener always uses the address that connected to it.