Support composite MCP servers (#4560)

This change introduces "Composite" MCP Servers and support for:

- Creating composite servers by combining multiple single or remote servers
- Composite 2nd level OAuth flow

This change does not include support for:

- Adding multi-user MCP servers to a composite server
- Upgrading composite MCP server instances and their child servers

Support for these will be included in follow up PRs.

Addresses part of #3553

---------

Signed-off-by: Nick Hale <[email protected]>

Author: njhale

apiclient/types/mcpserver.go

@@ -15,6 +15,7 @@ const (
 	RuntimeNPX           Runtime = "npx"
 	RuntimeContainerized Runtime = "containerized"
 	RuntimeRemote        Runtime = "remote"
+	RuntimeComposite     Runtime = "composite"
 )
 
 // UVXRuntimeConfig represents configuration for UVX runtime (Python packages via uvx)
@@ -54,6 +55,30 @@ type RemoteCatalogConfig struct {
 	Headers     []MCPHeader `json:"headers,omitempty"`     // Optional
 }
 
+// CompositeCatalogConfig represents configuration for composite servers in catalog entries.
+type CompositeCatalogConfig struct {
+	ComponentServers []CatalogComponentServer `json:"componentServers"`
+}
+
+// CatalogComponentServer represents a component server in a composite server catalog entry.
+type CatalogComponentServer struct {
+	CatalogEntryID string                        `json:"catalogEntryID"`
+	Manifest       MCPServerCatalogEntryManifest `json:"manifest"`
+	ToolOverrides  []ToolOverride                `json:"toolOverrides,omitempty"`
+	Disabled       bool                          `json:"disabled,omitempty"`
+}
+
+type CompositeRuntimeConfig struct {
+	ComponentServers []ComponentServer `json:"componentServers"`
+}
+
+type ComponentServer struct {
+	CatalogEntryID string            `json:"catalogEntryID"`
+	Manifest       MCPServerManifest `json:"manifest"`
+	ToolOverrides  []ToolOverride    `json:"toolOverrides,omitempty"`
+	Disabled       bool              `json:"disabled,omitempty"`
+}
+
 type MCPServerCatalogEntry struct {
 	Metadata
 	Manifest                  MCPServerCatalogEntryManifest `json:"manifest"`
@@ -83,10 +108,23 @@ type MCPServerCatalogEntryManifest struct {
 	NPXConfig           *NPXRuntimeConfig           `json:"npxConfig,omitempty"`
 	ContainerizedConfig *ContainerizedRuntimeConfig `json:"containerizedConfig,omitempty"`
 	RemoteConfig        *RemoteCatalogConfig        `json:"remoteConfig,omitempty"`
+	CompositeConfig     *CompositeCatalogConfig     `json:"compositeConfig,omitempty"`
 
 	Env []MCPEnv `json:"env,omitempty"`
 }
 
+// ToolOverride defines how a single component tool is exposed by the composite server
+type ToolOverride struct {
+	// Name is the original tool name as returned by the component server
+	Name string `json:"name"`
+	// OverrideName is the tool name exposed by the composite server
+	OverrideName string `json:"overrideName"`
+	// Optional overrides for display
+	OverrideDescription string `json:"overrideDescription,omitempty"`
+	// Whether to include this tool (default true)
+	Enabled bool `json:"enabled,omitempty"`
+}
+
 type MCPHeader struct {
 	Name        string `json:"name"`
 	Description string `json:"description"`
@@ -124,6 +162,7 @@ type MCPServerManifest struct {
 	NPXConfig           *NPXRuntimeConfig           `json:"npxConfig,omitempty"`
 	ContainerizedConfig *ContainerizedRuntimeConfig `json:"containerizedConfig,omitempty"`
 	RemoteConfig        *RemoteRuntimeConfig        `json:"remoteConfig,omitempty"`
+	CompositeConfig     *CompositeRuntimeConfig     `json:"compositeConfig,omitempty"`
 
 	Env []MCPEnv `json:"env,omitempty"`
 
@@ -354,6 +393,40 @@ func MapCatalogEntryToServer(catalogEntry MCPServerCatalogEntryManifest, userURL
 		remoteConfig.Headers = catalogEntry.RemoteConfig.Headers
 		serverManifest.RemoteConfig = remoteConfig
 
+	case RuntimeComposite:
+		if catalogEntry.CompositeConfig == nil {
+			return serverManifest, RuntimeValidationError{
+				Runtime: RuntimeComposite,
+				Field:   "compositeConfig",
+				Message: "composite configuration is required for composite runtime",
+			}
+		}
+
+		// Convert CatalogComponentServer to ComponentServer
+		componentServers := make([]ComponentServer, len(catalogEntry.CompositeConfig.ComponentServers))
+		for i, catalogComponent := range catalogEntry.CompositeConfig.ComponentServers {
+			// Convert the component's catalog manifest to server manifest
+			componentServerManifest, err := MapCatalogEntryToServer(catalogComponent.Manifest, "")
+			if err != nil {
+				return serverManifest, RuntimeValidationError{
+					Runtime: RuntimeComposite,
+					Field:   fmt.Sprintf("compositeConfig.componentServers[%d]", i),
+					Message: fmt.Sprintf("failed to convert component manifest: %v", err),
+				}
+			}
+
+			componentServers[i] = ComponentServer{
+				CatalogEntryID: catalogComponent.CatalogEntryID,
+				Manifest:       componentServerManifest,
+				ToolOverrides:  catalogComponent.ToolOverrides,
+				Disabled:       false,
+			}
+		}
+
+		serverManifest.CompositeConfig = &CompositeRuntimeConfig{
+			ComponentServers: componentServers,
+		}
+
 	default:
 		return serverManifest, RuntimeValidationError{
 			Runtime: catalogEntry.Runtime,

apiclient/types/zz_generated.deepcopy.go

@@ -17,6 +17,8 @@ var apiResources = map[string][]string{
 		"GET    /api/all-mcps/servers/{mcpserver_id}/prompts/{prompt_name}",
 		"GET    /oauth/callback/{oauth_request_id}/{mcp_id}",
 		"GET    /oauth/mcp/callback",
+		"GET    /auth/mcp/composite/{mcp_id}",
+		"GET    /api/oauth/composite/{mcp_id}",
 		"GET    /mcp-connect/{mcp_id}",
 		"POST   /mcp-connect/{mcp_id}",
 		"DELETE /mcp-connect/{mcp_id}",