VirtualMCPServer ignores `scopes` field in protected resource metadata (RFC 9728)

[gastoncan]

Version: v0.18.0 (operator + vmcp)

Summary: The scopes field in incomingAuth.oidcConfig.inline and incomingAuth.oidcConfigRef is accepted by the CRD and operator but ignored by the vmcp binary. The /.well-known/oauth-protected-resource endpoint always returns scopes_supported: ["openid"] regardless of configuration.

Impact: MCP clients (Claude Code, VS Code) read scopes_supported from the protected resource metadata to build their DCR registration request. When offline_access is not advertised, clients register without it → Keycloak creates the DCR client without offline_access as a valid scope → client auth fails with invalid_scope when requesting openid offline_access.

Steps to reproduce:

1. Create a VirtualMCPServer with scopes configured:

incomingAuth:
  type: oidc
  oidcConfigRef:
    name: my-oidc-config
    audience: "mcp-gateway"
    scopes:
      - openid
      - offline_access

2. Check the CR confirms the scopes:

$ kubectl get virtualmcpserver vmcp -n mcp -o json | jq '.spec.incomingAuth.oidcConfigRef.scopes'
["openid", "offline_access"]

3. Check the discovery endpoint:

$ curl -s https://mcp-gateway.domain/.well-known/oauth-protected-resource | jq .
{
  "resource": "https://mcp-gateway.domain/mcp",
  "authorization_servers": ["https://keycloak.domain/realms/mcp"],
  "bearer_methods_supported": ["header"],
  "scopes_supported": ["openid"]    ← offline_access missing
}

4. Also tested with incomingAuth.oidcConfig.type: inline and scopes inside the inline block — same result.

CRD documentation confirms the field should work:

scopes:
  description: |-
    Scopes is the list of OAuth scopes to advertise in the well-known endpoint (RFC 9728).
    If empty, defaults to ["openid"].

Expected: scopes_supported: ["openid", "offline_access"]
Actual: scopes_supported: ["openid"]

Environment: Operator v0.18.0, vmcp v0.18.0, Keycloak 26.3.3, Kubernetes 1.31

---

[jhrozek]

Thanks for the detailed report. I traced the scopes field through both code paths — external OIDC (oidcConfigRef → NewAuthInfoHandler) and embedded auth server (deriveScopesSupported → BuildAuthServerRunConfig) — and both correctly propagate scopes at every stage, including at the v0.18.0 tag. The ["openid"] fallback only activates when the scopes slice is empty.

I also deployed a reproducer on a kind cluster with a VirtualMCPServer configured with scopes: ["openid", "offline_access"] on oidcConfigRef and confirmed the endpoint returns the expected values:

{
    "scopes_supported": ["openid", "offline_access"]
}

Could you help narrow this down?

1. Which auth setup are you using? External Keycloak as the OIDC provider (just oidcConfigRef), or the embedded auth server fronting Keycloak (externalAuthConfigRef with type: embeddedAuthServer)?

2. Check the generated ConfigMap — does it contain your scopes?

   kubectl get configmap <vmcp-name>-vmcp-config -n <namespace> -o yaml | grep -A5 scopes
   

   If scopes are missing from the ConfigMap, the issue is in operator reconciliation. If they're present, the issue is in the vmcp binary's config loading.

3. Verify the vMCP pod image version:

   kubectl get pod <vmcp-pod> -n <namespace> -o jsonpath='{.spec.containers[*].image}'
   

4. Were scopes added to an existing VirtualMCPServer? If so, try deleting and recreating it to force a full reconciliation.

[gastoncan]

Thanks for investing such effort to reproduce the issue.
I can confirm it is a false positive, this is not a bug.
The problem in my env is that because of #4783, my env is not properly reconciling (the operator is killng my K8s control plane with Deployment create/destroy API calls), thus the ConfigMap is not fully updated.
I deleted the vmcp deployment, lettig the operator to recreate it, then the scopes started to be published properly.

Note that I only re-tested with incomingAuth.oidcConfig.inline.scopes, because incomingAuth.oidcConfigRef.scopes is blocked due to #4851.

Sorry for misleading you with this false positive issue.
Closing.