Unify Runtime MCP bindings and qualify workspace capabilities

Author: SaladDay

CONTRIBUTING.md

@@ -23,6 +23,7 @@ copy, when a contract changes.
 | Environment ownership and capability preparation (Skills, Plugins, MCP, `packages.system`) | [Environments](contracts/agents-api/environments.md) |
 | Adding a Harness (steps) | [Harness onboarding](contracts/agents-api/harness-onboarding.md), `apps/parsar-daemon/internal/agent/harness.go` and `internal/harnessconfig/harness.go` |
 | Built-in Harness identifiers, configuration/profile bindings and display names | `internal/harnessconfig/builtin/catalog.json` and its [generated reference](contracts/agents-api/harness-catalog.md) |
+| Effective MCP bindings and credential authority | [Environment MCP](contracts/agents-api/environments.md#skills-plugins-and-environment-mcp) and `apps/parsar-daemon/internal/agent/mcp_binding.go` |
 | Harness qualification and acceptance | [Harness integration](contracts/agents-api/harnesses.md) |
 | Harness selection and Agent defaults | [Harness selection](contracts/agents-api/harness-selection.md) |
 | Adding a Sandbox Provider | [Sandbox Provider guide](docs/sandbox-provider.md) and `services/agents-api/internal/sandbox/sandbox_provider.go` |

README.md

@@ -72,6 +72,7 @@ the [architecture guide](docs/architecture.md).
 | Build an application on the API | [Quickstart](docs/getting-started/quickstart.md), then the [Agents API guide](docs/api/public-agent-api.md) |
 | See a complete application | [Examples](docs/examples.md) |
 | Run agents on my own machine | [Self-hosted execution](docs/getting-started/self-hosted.md) |
+| Check verified Runtime capabilities and limits | [Capability qualification](contracts/agents-api/environment-capabilities-qualification.md) |
 | Understand the design | [Architecture](docs/architecture.md) |
 | Add a sandbox, harness or other component | [Developer guide](docs/development.md) |
 

README.zh-CN.md

@@ -68,6 +68,7 @@ Core 对外提供两组 API：
 | 基于 API 开发应用 | [快速开始](docs/getting-started/quickstart.md)，然后看 [Agents API 指南](docs/api/public-agent-api.md) |
 | 看一个完整的应用 | [示例](docs/examples.md) |
 | 在自己的机器上运行 Agent | [自托管执行](docs/getting-started/self-hosted.md) |
+| 查看 Runtime 能力和验收范围 | [能力验收记录](contracts/agents-api/environment-capabilities-qualification.md) |
 | 了解设计 | [架构说明](docs/architecture.md) |
 | 接入新的沙箱、Harness 或其他组件 | [开发指南](docs/development.md) |
 

apps/docs/content/docs/environments-and-files.mdx

@@ -641,17 +641,32 @@ initialized values override the selected declaration's variables. There is no
 Python sandbox launcher, mount policy, shell prefix or separate credential sandbox.
 Process groups and Windows Jobs own cancellation and descendant cleanup only.
 Claude composes MCP identity and observation with the same workspace profile;
-MiniMax keeps its existing supported transport qualification. A public capability
+MiniMax uses the same effective bindings for stdio and HTTP. A public capability
 advertisement must still match the installed engine's actual supported transport.
 
+Runtime resolves public HTTP declarations and installed Plugin MCP through
+`agent.ResolveMCPBindings` before adapter projection. Each transient binding
+retains its connection origin, transport, nullable tool allowlist, required flag,
+credential authority and installed stdio identity. Bindings are never persisted
+or logged. Duplicate identities and unavailable selected credentials reject.
+A service-origin request cannot silently become an Environment-origin connection;
+the existing public HTTP MCP profile remains service-origin `environment:none`.
+This internal consolidation does not qualify public `connection_origin=environment`.
+
 Environment-origin literal HTTP headers remain rejected for the pinned Claude
-client because its interpolation and cross-origin forwarding change their meaning.
-MiniMax accepts environment stdio only. Its adapter reads the existing Session-private
-native runtime-name registry for exact first-frame identities and cross-checks
-completed native results. Reuse existing observation and cancellation settlement;
-never fabricate a delayed start event, guess normalized identities or add a registry
-of our own. Its unqualified HTTP transport remains rejected.
-These mechanisms alone do not establish public MCP support or full compatibility.
+and MiniMax clients because their cross-origin forwarding cannot preserve header
+authority. MiniMax supports installed stdio and HTTP servers with anonymous or
+explicit user-selected HTTPS bearer authentication. ACP HTTP declarations remain
+Session-local native memory; tokens do not enter native configuration files or
+process arguments. Required initialization and tool allowlists are not exposed
+through the Plugin manifest, and public MiniMax MCP remains unqualified.
+MiniMax reads the existing Session-private native runtime-name registry for exact
+first-frame identities and cross-checks completed native results for both transports.
+Reuse existing observation and cancellation settlement; never fabricate a delayed
+start event, guess normalized identities or add a registry of our own.
+
+See [capability qualification](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/environment-capabilities-qualification.md) for
+real model evidence and the remaining public-origin and image gaps.
 
 ## Contract inventory
 

apps/docs/content/guide-sources.json

@@ -13,7 +13,7 @@
     "contracts/agents-api/execution-tools.md": "e0b61f6c0c236c362186c5f6d0ad69a16dd8a8d9afabe1329a1fe22e5f4a71e9",
     "docs/api/public-agent-api.md": "00979732412a971013e8f01b4c74820ff51aafdded6b0f105d25a78af86a6627",
     "docs/examples.md": "0e1bdaeff51c9c36779f817be31ea9816b7d8cb2290cf8350d3c4801f436f4f9",
-    "contracts/agents-api/environments.md": "d5fc16c904f751bd13e2af35c9e43c92ca39c6b86401f85cf7f9ee4093c156c9",
+    "contracts/agents-api/environments.md": "a000ca89f5d7611f52c963467dd72f2ab5195d2e3dc48a0aeefb89fd9bcfc7a6",
     "docs/getting-started/nodes.md": "c1ad18c445990ea696625011cc3cfa0725779beefd379064d278656801d5578e",
     "docs/getting-started/self-hosted.md": "5ade597e09cbfa2e321f341693b47730b3696fe7bd4d6834eafbe6b279a55e6b",
     "docs/self-hosted-native.md": "b3cf736f88792e6925c50b81a4c33eba6b9ee86e195f9ed4e2187db7bed71d88",
@@ -44,7 +44,7 @@
     "content/docs/agents-and-tools.mdx": "b8a85fe92e19a71b7ad7c9357ce7ad0595d50c9190edb748ca834df615b056cb",
     "content/docs/sessions.mdx": "bb63d799ed90038836d652f3f866d0309822425114c6b2aa36654b8a991947f6",
     "content/docs/examples.mdx": "587061e65ab2e841d14980539ba94e2216d4e8135c948a852b9a8bb0359c85d7",
-    "content/docs/environments-and-files.mdx": "352ca1f2b0ab1b0853b890be694629bb47399ba6bc88905f68feaa3bfe401949",
+    "content/docs/environments-and-files.mdx": "a35d35841740e6f9092506e019bf23675a0946b1e9f1ff61dc561cd11b64d152",
     "content/docs/hosted-providers.mdx": "85696d88b76f1233db3d8db3266bb0ab4d297d795a44ede13cf34e5169524c68",
     "content/docs/self-hosted-execution.mdx": "eeed4c6b3646927ccc3c7ac2d20b2c0f9c8a65e42d734310fe3959e016324e57",
     "content/docs/self-hosted-native.mdx": "671451580dfb4f5c134221991f68292a4f992008174d23190b1da3742046571f",

apps/parsar-daemon/internal/agent/claudesdk/mcp_environment.go

@@ -3,6 +3,7 @@ package claudesdk
 import (
 	"fmt"
 
+	"github.com/MiniMax-AI-Dev/parsar/apps/parsar-daemon/internal/agent"
 	"github.com/MiniMax-AI-Dev/parsar/apps/parsar-daemon/internal/localworkspace"
 	"github.com/MiniMax-AI-Dev/parsar/internal/agentdaemon/proto"
 )
@@ -15,45 +16,34 @@ type environmentMCPServer struct {
 	Args    []string `json:"args,omitempty"`
 }
 
-func prepareEnvironmentMCP(environment *proto.LocalEnvironment) ([]environmentMCPServer, []string, error) {
-	if environment == nil || len(environment.MCP) == 0 {
-		return nil, nil, nil
-	}
-	if environment.NetworkAccess != "enabled" {
-		return nil, nil, fmt.Errorf("claudesdk: environment MCP requires enabled network")
+func prepareRuntimeMCP(req proto.PromptRequestPayload) ([]environmentMCPServer, []string, error) {
+	bindings, err := agent.ResolveMCPBindings(req)
+	if err != nil {
+		return nil, nil, err
 	}
 	var servers []environmentMCPServer
 	var env []string
-	labels := map[string]bool{}
-	for _, item := range environment.MCP {
-		declaration := item.Server
-		if !mcpLabel.MatchString(declaration.Name) || declaration.Name == "functions" || labels[declaration.Name] {
-			return nil, nil, fmt.Errorf("claudesdk: unsupported environment MCP identity")
+	for _, binding := range bindings {
+		if !mcpLabel.MatchString(binding.ServerLabel) || binding.ServerLabel == "functions" {
+			return nil, nil, fmt.Errorf("claudesdk: unsupported MCP identity")
+		}
+		if binding.Stdio != nil {
+			command, args := localworkspace.MCPStdioCommand(*binding.Stdio)
+			servers = append(servers, environmentMCPServer{mcpHTTPServer: mcpHTTPServer{ServerLabel: binding.ServerLabel}, Command: command, Args: args})
+			continue
+		}
+		// Native header interpolation and redirect behavior cannot preserve literal
+		// custom-header authority. Reject this unqualified combination explicitly.
+		if len(binding.HTTPHeaders) != 0 {
+			return nil, nil, fmt.Errorf("claudesdk: literal MCP HTTP headers are not supported")
 		}
-		labels[declaration.Name] = true
-		switch declaration.Type {
-		case "stdio":
-			command, args := localworkspace.MCPStdioCommand(item)
-			servers = append(servers, environmentMCPServer{mcpHTTPServer: mcpHTTPServer{ServerLabel: declaration.Name}, Command: command, Args: args})
-		case "http":
-			// The pinned native client expands literal headers again and forwards
-			// custom headers across origins. Do not reinterpret their public meaning.
-			if len(declaration.HTTPHeaders) != 0 {
-				return nil, nil, fmt.Errorf("claudesdk: environment MCP literal HTTP headers are not supported")
-			}
-			if declaration.BearerTokenEnvVar != "" && item.BearerToken == nil {
-				return nil, nil, fmt.Errorf("claudesdk: environment MCP credential unavailable")
-			}
-			http := []proto.MCPHTTPServer{{ServerLabel: declaration.Name, ServerURL: declaration.URL, BearerToken: item.BearerToken}}
-			if err := validateMCPServers(http); err != nil {
-				return nil, nil, err
-			}
-			projected, credentials := prepareMCPHTTP(&http)
-			servers = append(servers, environmentMCPServer{mcpHTTPServer: (*projected)[0]})
-			env = append(env, credentials...)
-		default:
-			return nil, nil, fmt.Errorf("claudesdk: unsupported environment MCP transport")
+		declarations := []proto.MCPHTTPServer{{ServerLabel: binding.ServerLabel, ServerURL: binding.ServerURL, AllowedTools: binding.AllowedTools, Required: binding.Required, BearerToken: binding.BearerToken}}
+		if err := validateMCPServers(declarations); err != nil {
+			return nil, nil, err
 		}
+		projected, credentials := prepareMCPHTTP(&declarations)
+		servers = append(servers, environmentMCPServer{mcpHTTPServer: (*projected)[0]})
+		env = append(env, credentials...)
 	}
 	return servers, env, nil
 }

apps/parsar-daemon/internal/agent/claudesdk/mcp_environment_test.go

@@ -66,7 +66,7 @@ func TestEnvironmentMCPRejectsUnqualifiedCombinations(t *testing.T) {
 	} {
 		environment := &proto.LocalEnvironment{NetworkAccess: "enabled", MCP: []proto.EnvironmentMCP{{InstallationRoot: "/private/runtime/capabilities", WorkspaceRoot: "/private/runtime/workspace", PackageRoot: "plugins/remote", Server: agentplugin.MCPServer{Name: "remote", Type: "http", URL: "https://example.invalid/mcp"}}}}
 		mutate(environment)
-		if _, _, err := prepareEnvironmentMCP(environment); err == nil {
+		if _, _, err := prepareRuntimeMCP(proto.PromptRequestPayload{LocalEnvironment: environment}); err == nil {
 			t.Fatal("unsupported declaration accepted")
 		}
 	}

apps/parsar-daemon/internal/agent/claudesdk/options.go

@@ -71,7 +71,7 @@ func prepareConfiguration(config Config, req proto.PromptRequestPayload) (startR
 		return startRequest{}, nil, err
 	}
 	if req.ToolSearch {
-		if config.Workspace != nil || req.LocalEnvironment != nil || req.MCPHTTPServers != nil || !req.DisableSubagents || (req.ExecutionControls != nil && req.ExecutionControls.OutputFormat != nil) {
+		if (req.LocalEnvironment != nil && (len(req.LocalEnvironment.Skills) != 0 || len(req.LocalEnvironment.MCP) != 0)) || req.MCPHTTPServers != nil || !req.DisableSubagents || (req.ExecutionControls != nil && req.ExecutionControls.OutputFormat != nil) {
 			return fail("tool discovery requires the single-agent text/function profile")
 		}
 		start.ToolSearch = true
@@ -187,8 +187,17 @@ func prepareConfiguration(config Config, req proto.PromptRequestPayload) (startR
 	}
 	env := withProvider(append(append([]string{}, os.Environ()...), config.Env...), provider)
 	env = append(env, "CLAUDE_CONFIG_DIR="+config.StateDir, "TMPDIR="+filepath.Join(config.StateDir, "tmp"), "DISABLE_TELEMETRY=1", "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1")
-	var mcpEnv []string
-	start.MCPHTTPServers, mcpEnv = prepareMCPHTTP(req.MCPHTTPServers)
+	projectedMCP, mcpEnv, err := prepareRuntimeMCP(req)
+	if err != nil {
+		return startRequest{}, nil, err
+	}
+	if req.MCPHTTPServers != nil {
+		servers := make([]mcpHTTPServer, 0, len(projectedMCP))
+		for _, server := range projectedMCP {
+			servers = append(servers, server.mcpHTTPServer)
+		}
+		start.MCPHTTPServers = &servers
+	}
 	env = append(env, mcpEnv...)
 	return start, env, nil
 }

apps/parsar-daemon/internal/agent/claudesdk/readiness.go

@@ -37,6 +37,10 @@ func (info RuntimeInfo) SupportsToolSearch() bool {
 	return slices.Contains(info.Features, "tool_search")
 }
 
+func (info RuntimeInfo) SupportsWorkspaceToolSearch() bool {
+	return info.SupportsWorkspaceFunctions() && info.SupportsToolSearch() && slices.Contains(info.Features, "workspace_tool_search")
+}
+
 func (info RuntimeInfo) SupportsStructuredOutput() bool {
 	return slices.Contains(info.Features, "structured_output")
 }

apps/parsar-daemon/internal/agent/claudesdk/readiness_test.go

@@ -149,3 +149,17 @@ func runReadinessHelper() {
 		os.Exit(3)
 	}
 }
+
+func TestWorkspaceToolSearchRequiresNativeWorkspaceFeature(t *testing.T) {
+	features := []string{"tool_search", "workspace_tool_search", "workspace_functions", "workspace_tools", "workspace_prepare", "workspace_command_observations", "local_runtime_v2"}
+	if !(RuntimeInfo{Features: features}).SupportsWorkspaceToolSearch() {
+		t.Fatal("complete workspace discovery contract rejected")
+	}
+	for omitted := range features {
+		candidate := append([]string{}, features[:omitted]...)
+		candidate = append(candidate, features[omitted+1:]...)
+		if (RuntimeInfo{Features: candidate}).SupportsWorkspaceToolSearch() {
+			t.Fatal("incomplete native discovery contract advertised")
+		}
+	}
+}