Remote MCP server
AI agent clients connect to /mcp on the API host over the Model Context
Protocol and read Waldur data as the signed-in user. They sign in with OAuth,
or with a personal access token. A separate waldur-mastermind-mcp
Deployment runs waldur mcp_server; the API serves the OAuth endpoints.
Enabling
1 2 3 4 5 6 7 | |
Then turn on the MCP_ENABLED setting, in the admin UI or through
waldur.settingsOverrides. Until then, /mcp and the OAuth endpoints answer
404.
The chart then:
- runs
waldur mcp_serverpods and awaldur-mastermind-mcpService. The server is stateless, so replicas need no session affinity; - routes these paths on the API hosts (
apiHostname, orlocalApiHostname, andapiExtraHosts), through an Ingress or an HTTPRoute:
| Path | Served by |
|---|---|
/mcp |
MCP pods |
/.well-known/oauth-protected-resource |
MCP pods |
/.well-known/oauth-authorization-server |
API |
/oauth/authorize, /oauth/token, /oauth/revoke_token, /oauth/register |
API |
/oauth/consent is not among them: it's the portal page where users
approve a client, and the portal often shares the API's host;
- seeds MCP_RESOURCE_URLS with <apiScheme>://<host>/mcp for
apiHostname and then each of apiExtraHosts, space-separated. Clients
reject resource metadata that names another host than the one they
connected to. While the setting is empty, Waldur issues no OAuth token and
clients can only use personal access tokens. To set it yourself, put the
whole value in waldur.settingsOverrides, which then wins. Like every
seeded setting, it is applied by the init-whitelabeling hook, which runs
only while waldur.initdbEnabled is true; otherwise set it in the admin
UI;
- adds a NetworkPolicy for the MCP pods when networkPolicy.enabled is set.
The API pods already allow outbound HTTPS, which they need to fetch the
metadata of clients that identify themselves by URL.
What the pods get
The MCP pods face the internet, so they get less than the API pods:
- of the mounted files, only the settings file (
override.conf.py), none of the SSH keys, kubeconfig or other files the API pods mount; - of the environment variables the chart gives mastermind pods, only the
database, the RabbitMQ broker, the Django and field encryption keys, Sentry
and the outbound proxy. Not the mail, LDAP, eduTEAMS or DataCite
credentials. The list is an allowlist (
waldur.mcp.credentialsin_helpers.tpl), so a variable the chart adds later stays out until it is named there; - no service account token, no Linux capabilities, no privilege escalation, a
read-only root filesystem and the
RuntimeDefaultseccomp profile. The server can write only to/tmp. Thewait-for-migrationsinit container gets the same restrictions and variables, and no writable path.
Every mastermind pod mounts the same settings file, so secrets the chart writes into it reach the MCP pods too:
waldur.ldap.passwordand the eduTEAMSclientSecret,refreshTokenandsshApiPassword. Set them throughwaldur.ldap.passwordExistingSecretandwaldur.remoteEduteams.existingSecretinstead, and they stay out;- the
tokenSecretofcustomInvitations,serviceAccountApiIntegrationandcourseAccountApiIntegration, which have no Secret option.
The pods run as the image's waldur user. The chart sets no runAsNonRoot:
the image names that user rather than a UID, which the kubelet can't check.
Database connections
Each MCP pod holds up to dbThreads Postgres connections.
replicas × dbThreads counts against Postgres max_connections, on top of
the API and Celery pods.
CORS
Browser-based MCP clients call these routes from their own origin. Clients
that call /mcp from a server or a desktop app don't need CORS.
- OAuth endpoints. Waldur answers them with
Access-Control-Allow-Origin: *and no credentials, and that answer has to reach the browser. On nginx they are on their own Ingress,mcp-oauth-ingress, withoutenable-cors: ingress-nginx would answer preflights itself and swap*for the caller's origin plusAllow-Credentials. Traefik'sapi-corsmiddleware and HAProxy'scors-enableanswer with*and no credentials too, and allow theMCP-Protocol-Versionheader. /mcpand its metadata. The MCP server answers CORS itself, withAccess-Control-Allow-Origin: *, no credentials, any request header, andWWW-Authenticateexposed so that a browser can read the 401 challenge.mcp-ingressadds no CORS of its own on any controller: on Traefik it goes throughmcp-chain, which isapi-chainwithoutapi-cors. Images up to 8.1.5-rc.2 send no CORS there, so a client that calls/mcpfrom a web page needs a later mastermind image.- Gateway API. The chart adds no CORS. Don't add a CORS policy to
mcp-httprouteormcp-oauth-httprouteingatewayAPI.extraPolicies: it would replace Waldur's own answer.
IP allow-listing
On the Ingress path, ingress.whitelistSourceRange covers the MCP routes as
it covers the API. On the Gateway API path, an allow-list policy in
gatewayAPI.extraPolicies covers only the routes it targets: add
mcp-httproute and mcp-oauth-httproute next to api-httproute, or /mcp
and the OAuth endpoints stay open to everyone.
Behind more than one proxy
The throttle on new OAuth clients keys on an X-Forwarded-For entry, as the
limit on failed passwords does. waldur.trustedProxyCount sets both; see
IP whitelisting.
Checking it
With MCP_ENABLED on, the resource metadata names the seeded URL:
1 2 | |
A request to /mcp without a token answers 401, with a WWW-Authenticate
header that points at that metadata.