MCP Listener¶
The MCP server runs inside the engine on a port of its own, the MCP Port, separate from the console and the Management API. Clients send their requests there; they sign in through the console (see MCP Client Sign-In). A Remote Management Hub runs a listener of its own in the same way (see The MCP Server on a Hub). Calls that reach an engine through its Hub do not use the listener: they arrive through the engine's tunnel to the Hub (see MCP Calls Through the Hub).
The MCP page refuses a port the console, the Management API or a channel already uses. While the MCP server is enabled, View Ports lists its port, and a new channel is never offered it. A channel port set by a node tag is compared as View Ports shows it, by its tag, so the page does not catch a clash with the port the tag resolves to.
Starting and stopping¶
The engine starts the listener when it starts, if the MCP server is enabled, and stops it when it shuts down. Saving the MCP settings rebuilds the listener on every node in a cluster, so a change takes effect without a restart. Turning the MCP server off stops the listener on every node; clients can no longer connect, although their sign-ins stay until they are revoked or expire.
If the listener cannot start, for example because another program uses the MCP Port or the server certificate cannot be used, the engine log gets a warning, or an error when the cause is something unexpected, and the engine tries again every minute. If the listener stops on its own, the engine starts it again within a minute. A Hub starts its listener once the Hub has started, and its process monitor tries again in the same way.
HTTPS only¶
The listener accepts HTTPS only. It presents the Server Certificate chosen in MCP Settings, a certificate from Global Settings with its private key and its chain. The MCP server cannot be enabled without a port and a server certificate.
The listener leaves out the weak cipher suites the console and HTTP receivers leave out, unless qie.enableWeakCipherSuites is on. It also follows the qie.excludeCipherSuites, qie.includeCipherSuites and qie.excludeProtocols options set for the MCP Port (see Java Options).
With Client Auth on, the listener asks every client for a certificate and accepts only certificates issued by one of the selected Certificates. A client without one cannot connect at all.
The address clients use¶
Clients reach the listener at the Resource URL. The listener answers only requests addressed to that host name and port: a request that names any other host, such as one node's own name in a cluster, is refused with HTTP 403. Clients must therefore use the address the Resource URL names, and in a cluster that is the shared name (see Deploying the MCP Server).
A request from a web page carries an Origin header. The listener refuses one whose origin is not the Resource URL's own, so a web page cannot use a person's browser to call the MCP server. Clients that are not browsers send no Origin and are not affected.
Before a client signs in¶
Some answers need no sign-in, so a client can discover how to sign in:
- The protected resource document, at
/.well-known/oauth-protected-resource/mcpand/.well-known/oauth-protected-resource, names the console as the authorization server and lists the scopes. - A request to the MCP endpoint without a token is answered with HTTP 401 and a
WWW-Authenticateheader that points to that document and asks for read-only access.
Signed-in requests¶
Every request to the MCP endpoint carries the client's access token. QIE checks it on every request: the token must be one QIE issued, not revoked, not expired, and issued for the Resource URL as it is set now. It also checks the user's account the way the console does at sign-in. A disabled or locked account, a temporary password or an expired password is refused with the same reason the console gives, and the client is asked to sign in again. What the user may do is checked on every call against their current rights, so a change to a user's zone permissions applies to the next call.
Every refused request writes an entry to the MCP audit log. A request whose token is refused also counts toward the address's allowance for requests without a token (below).
Protocol versions¶
The MCP server accepts MCP protocol versions 2025-06-18 and 2025-11-25. A client that asks for another version is refused with a message naming the two, so it can be updated.
Limits before sign-in¶
The listener applies these limits before it looks at a token:
| Limit | Value | Answer |
|---|---|---|
| Requests without a valid token from one address | Unauthenticated Requests per Address per Minute, 60 by default | HTTP 429 with a Retry-After header |
| Open streams from one address | 8 | HTTP 429 |
| Size of one request | 1 MB, except a call to describe_package, import_configuration or import_certificates, or create_job on a Hub, from a signed-in client, which may reach the Package Ceiling (bytes) plus 1 MB |
HTTP 413 |
| Nesting of the JSON in one request | 64 levels | HTTP 400 |
The first request over the per-address limit in a minute also writes an audit entry and raises the abuse alert described in Alerts. The address the limits count is always the address that connected, never a forwarded header.
Limits after sign-in¶
Once a token is accepted, the listener applies limits to the sign-in it belongs to:
| Limit | Value | Answer |
|---|---|---|
| Requests | Requests per Token per Minute, 120 by default | HTTP 429 with a Retry-After header |
| Message searches | Message Searches per Token per Minute, 10 by default | HTTP 429 with a Retry-After header |
| Tool calls and resource reads running at once | Concurrent Requests per Token, 8 by default | Waits up to 2 seconds for one to finish, then HTTP 429, retry after 1 second |
| Open streams | 4 | HTTP 429 |
Only tool calls and resource reads (a guide, a help page or the Code Wizard reference) count as running at once. The requests a client sends together when it connects, such as the lists of tools, resources and prompts, do not count, so connecting never uses up the allowance. A sign-in keeps its counts when the client refreshes its access token, so refreshing does not reset them. The first request over a limit in a minute writes an entry to the MCP audit log, and the engine log gets a warning for each refused request, at most ten an hour for one address followed by a summary.
Limits count per node¶
Every limit on this page is counted in memory on each node. In a cluster behind a load balancer, a client can therefore make up to the limit on each node: with two nodes and the default of 120 requests per token per minute, up to 240 in a minute. Set the limits with the number of nodes in mind.
Access log¶
Every request to the listener writes one line to the console access log (access.log), including requests that are refused before sign-in. The line gives the method, the path without its query string, the user and client the token belongs to (or - before sign-in), the address that connected, the HTTP status and how long the request took. It never contains a query string, a header or a token. A request the server answers as a stream is logged when the stream ends.
Worker threads¶
The listener receives requests on its own pool of Worker Threads, 16 by default, and runs tool calls on a separate pool, so MCP calls never take threads from the console or from channels. Concurrent Requests per Token limits how many calls one sign-in runs at once.
Ports and connections¶
| Port | Who connects | Over | What for |
|---|---|---|---|
| MCP Port | MCP clients | HTTPS | Tool calls, and the protected resource document |
| Console port | The person's browser | HTTPS | Sign-in and approval |
| Console port | MCP clients | HTTPS | Registration, tokens and revocation |
| 443, or the port a Metadata Document Hosts entry names, outbound from the engine | Hosts on Metadata Document Hosts | HTTPS | Client metadata documents, only while that list holds a host |