[MCP] feat: Add realm support

[MonkeyCanCode]

Current mcp implementation lacks of support for realm context as everything is default to the default realm. To supports environments with multiple realms, this PR adds the following:

1. Realm specific CLIENT_ID, CLIENT_SECRET, TOKEN_SCOPE, and TOKEN_URL
2. New config POLARIS_REALM_CONTEXT_HEADER_NAME to overwrite default realm name in HTTP header
3. Add support for realm specific auth token caching

Sample output:

Call without realm:

2025-11-28 12:34:40.850 [warning] [server stderr] {"asctime": "2025-11-28 12:34:40,849", "name": "polaris_mcp.server", "levelname": "INFO", "message": "Tool call result", "isError": false, "meta": {"method": "GET", "url": "http://localhost:8181/api/management/v1/catalogs", "status": 200, "request": {"method": "GET", "url": "http://localhost:8181/api/management/v1/catalogs", "headers": {"Accept": "application/json", "Authorization": "[REDACTED]"}}, "response": {"status": 200, "headers": {"Content-Type": "application/json;charset=UTF-8", "content-length": "15", "X-Request-ID": "1be22f89-ec71-40d6-b809-1e7f73a9df85_0000000000000000002"}, "body": {"catalogs": []}}}}

Call with realm:

2025-11-28 12:34:53.077 [warning] [server stderr] {"asctime": "2025-11-28 12:34:53,076", "name": "polaris_mcp.server", "levelname": "INFO", "message": "Tool call result", "isError": false, "meta": {"method": "GET", "url": "http://localhost:8181/api/management/v1/catalogs", "status": 200, "request": {"method": "GET", "url": "http://localhost:8181/api/management/v1/catalogs", "headers": {"Accept": "application/json", "Authorization": "[REDACTED]", "Polaris-Realm": "POLARIS"}}, "response": {"status": 200, "headers": {"Content-Type": "application/json;charset=UTF-8", "content-length": "15", "X-Request-ID": "1be22f89-ec71-40d6-b809-1e7f73a9df85_0000000000000000004"}, "body": {"catalogs": []}}}}

[flyrain]

Thanks a lot for working on it, @MonkeyCanCode ! LGTM overall. Left one minor comment.

[flyrain]

Should we raise an error here if the realm isn't configured in the current MCP server? Either because that realm is invalid or MCP server just didn't configure it. We could have common method for that, as each tool needs it. Not a blocker though. I'm fine with a followup.

[MonkeyCanCode]

But realm is optional as if user didn't provide the realm, it will not be set via header. In this case, it will continue to work with Polairs server as it will just default to the first set realm in polaris.realm-context.realms.

[flyrain]

Sorry, I may not have expressed myself clearly earlier. Let me restate it: if the realm config is missing, it should absolutely fall back to the non-realm setting. However, if a user explicitly configures a realm but that realm is invalid or not configured, we should fail fast rather than silently falling back.

[MonkeyCanCode]

Got it. Yes, the latest PR ensure of realm specific auth is provided but failed, it will not fail back to the default one.

[flyrain]

Should we fail fast when realm specific credentials are there? Falling back to the global one may not always be the expected behavior. Along with my comment here, https://github.com/apache/polaris-tools/pull/83/files#r2582866657, I think it may be a good idea to build a list of realms and their credentials first based on the configurations, so that we can alway fail fast for invalid/un-configured realms.

The only downside is that the MCP server cannot support dynamic configurations, like adding a new env variable when it's running, which seems fine to me. We will clarify that isn't supported.

[MonkeyCanCode]

Good point. Yeah, I was thinking maybe users will use same credential for diff realm and not wanting to set credential for each of them (which is currently a support deployed model with polaris server). But I think the fail-fast may be better route in this case and this also matches to what we are asking users to do via current polaris CLI:

Loading profiles from /Users/yong/.polaris/.polaris.json
Polaris Client ID: xxxxx
Polaris Client Secret: xxxxx
Polaris Host [localhost]:
Polaris Port [8181]:
Polaris Context Realm:
Polaris Context Header Name [Polaris-Realm]:
Polaris profile new created successfully.

Regarding the comment mentioned above, do we want to realm an implicit config as it can be optional and server can still support.

Let me update this to reflect this change.

[MonkeyCanCode]

@flyrain above change is completed. Do you mind take another look when you have a chance?

[flyrain]

I was thinking maybe users will use same credential for diff realm and not wanting to set credential for each of them (which is currently a support deployed model with polaris server).

That's a valid point. Thanks for pointing it out. Do we want the config without realm to handle both: 1. global setting to all realms, 2. REST calls without realm header? My minor concern is that it may confuse users. For use case 1, we mighty introduce a new config like, POLARIS_GLOBAL_CLIENT_ID. I don't have a strong option on this though. Happy to discuss further.

Thanks for the change. LGTM!

[MonkeyCanCode]

Yeah, maybe let's proceed with this for now (not fall back and quick fail if missing). So the behavior is matching to the CLI.