Support multi-tenant OAuth deployments in oracle-mcp-common

[gsharini]

Summary

Add reusable multi-tenancy support to oracle-mcp-common so OCI MCP servers can be deployed as a single Streamable HTTP service that securely serves multiple OCI tenancies.

The OCI Recovery MCP server has implemented this capability in PR #403, including a tenancy registry, per-tenancy OAuth configuration, request routing, and isolation. This issue proposes moving the reusable authentication and tenancy-routing behavior into oracle-mcp-common so other OCI MCP servers can adopt a consistent implementation.

Problem

Most OCI MCP servers currently assume one configured tenancy per server process. This requires operators who serve multiple OCI tenancies to run and manage a separate MCP deployment for each tenancy.

For managed or shared deployments, a single MCP endpoint should be able to serve multiple tenancies while ensuring that:

• each caller authenticates only against their own tenancy’s IAM domain;
• OCI SDK clients use credentials derived from the authenticated caller;
• tenants cannot route requests to another tenancy by changing a request header;
• OAuth configuration, client secrets, token verification, and callback paths remain isolated per tenancy.

Proposed changes

Extend oracle-mcp-common with reusable multi-tenant HTTP/OAuth support based on the Recovery MCP implementation in PR #403.

The shared capability should provide:

• a server-side tenancy registry, configured from a TOML file or equivalent secure configuration source;
• a URL-safe tenancy alias for each configured tenancy;
• per-tenancy configuration for tenancy OCID, region, IAM domain, OAuth client ID, client secret, and audience;
• tenant selection for MCP requests using an X-OCI-Tenancy header;
• tenant-specific OAuth discovery, registration, authorization, token, and callback routes;
• caller-specific OCI authentication contexts and SDK clients;
• token verification that determines and stamps the verified tenant identity, rather than trusting a mutable request header;
• tenant-scoped OAuth state and secret-safe logging/error handling;
• a single-tenant configuration path that remains backward compatible.

Acceptance criteria

• oracle-mcp-common exposes a documented API for loading and validating a multi-tenant registry.
• A single Streamable HTTP MCP server process can serve multiple OCI tenancies.
• Each tenancy can define its own IAM domain, OAuth application credentials, audience, region, and tenancy OCID.
• Clients can select a tenancy using X-OCI-Tenancy by alias or tenancy OCID.
• In a multi-tenant deployment, requests without a valid tenancy selection return a clear tenancy_required error.
• OAuth redirects and callbacks are isolated per tenancy.
• Token verification and OCI request routing are bound to the tenant proven by the access token.
• HTTP-derived OCI signers and clients are not cached across callers or tenants.
• Registry validation rejects duplicate tenancy IDs, invalid aliases, incomplete entries, and insecure configuration.
• Secrets never appear in logs, exceptions, or object representations.
• Existing single-tenant and stdio authentication modes continue to work unchanged.
• At least one additional OCI MCP server adopts the common implementation as a reference integration.
• Documentation includes deployment configuration and client examples for both single-tenant and multi-tenant modes.

Reference implementation

PR #403 adds multi-tenant OAuth support to the OCI Recovery MCP server. Its tenancy registry, X-OCI-Tenancy routing model, per-tenant callback paths, and token-bound routing provide a useful starting point for the shared implementation.