feat: Support MCP Authentication

.agents/skills/contribute-adapter/SKILL.md

@@ -68,7 +68,7 @@ uv sync --group adapter-tests
 uv run --no-sync pytest tests/adapters/test_<name>*.py
 just test-python
 just lock-python && just wheels
-cargo run -p nemo-fabric-core --example generate-schemas -- schemas
+just schemas
 cargo fmt --all -- --check && just test-rust
 just docs
 uv run pre-commit run --all-files --show-diff-on-failure

adapter-contract/src/nemo_fabric_adapter_contract/codec.py

@@ -164,6 +164,8 @@ def encode_dataclass(instance: Any) -> dict[str, Any]:
             continue
         if item.metadata.get("omit_empty") and not value:
             continue
+        if "omit_default" in item.metadata and value == item.metadata["omit_default"]:
+            continue
         result[item.name] = _encode_value(value, path=(item.name,))
     return result
 
@@ -187,6 +189,16 @@ def _decode_value(
         if type(None) in arguments and value is None:
             return None
         options = tuple(option for option in arguments if option is not type(None))
+        if isinstance(value, Mapping) and "type" in value:
+            tagged_options = [
+                option
+                for option in options
+                if isinstance(option, type)
+                and get_origin(_resolved_type_hints(option).get("type")) is Literal
+                and value["type"] in get_args(_resolved_type_hints(option)["type"])
+            ]
+            if len(tagged_options) == 1:
+                return _decode_value(tagged_options[0], value, path=path)
         errors = []
         for option in options:
             try:

adapter-contract/src/nemo_fabric_adapter_contract/models.py

@@ -41,6 +41,10 @@ def _empty_list():
     return field(default_factory=list, metadata={"omit_empty": True})
 
 
+def _default(value: Any):
+    return field(default=value, metadata={"omit_default": value})
+
+
 def _json_value_field(*, default: Any = MISSING, omit_empty: bool = False):
     metadata = {"json": True}
     if omit_empty:
@@ -210,6 +214,108 @@ def _validate_tool_names(value: list[str] | None, field_name: str, label: str) -
         )
 
 
+class OAuthTokenEndpointAuthMethod(StrEnum):
+    """OAuth client authentication method used at the token endpoint."""
+
+    NONE = "none"
+    CLIENT_SECRET_POST = "client_secret_post"
+    CLIENT_SECRET_BASIC = "client_secret_basic"
+
+
+@dataclass(slots=True, kw_only=True)
+class McpOAuth2Config(ContractModel):
+    """OAuth 2.0 authorization-code authentication for an MCP server."""
+
+    type: Literal["oauth2"]
+    client_id: str | None = _optional()
+    client_secret_env: str | None = _optional()
+    scopes: list[str] = _empty_list()
+    redirect_uri: str | None = _optional()
+    enable_dynamic_registration: bool = _default(True)
+    client_name: str | None = _optional()
+    token_endpoint_auth_method: OAuthTokenEndpointAuthMethod | None = _optional()
+    authorization_timeout_seconds: int = _default(300)
+
+    @property
+    def scope(self) -> str | None:
+        """Return scopes in the space-delimited form expected by OAuth clients."""
+
+        value = " ".join(self.scopes)
+        return value or None
+
+    def _validate(self) -> None:
+        for name in ("client_id", "client_secret_env", "redirect_uri", "client_name"):
+            if (value := getattr(self, name)) is not None:
+                _nonblank(value, name)
+        _validate_tool_names(self.scopes, "scopes", "authentication scope")
+        if self.client_secret_env is not None and self.client_id is None:
+            raise ContractValidationError(
+                "requires client_id", path=("client_secret_env",)
+            )
+        if not self.enable_dynamic_registration and self.client_id is None:
+            raise ContractValidationError(
+                "is required when dynamic registration is disabled",
+                path=("client_id",),
+            )
+        if (
+            self.token_endpoint_auth_method
+            in {
+                OAuthTokenEndpointAuthMethod.CLIENT_SECRET_BASIC,
+                OAuthTokenEndpointAuthMethod.CLIENT_SECRET_POST,
+            }
+            and self.client_id is not None
+            and self.client_secret_env is None
+        ):
+            raise ContractValidationError(
+                "requires client_secret_env for a pre-registered client",
+                path=("token_endpoint_auth_method",),
+            )
+        if (
+            self.token_endpoint_auth_method is OAuthTokenEndpointAuthMethod.NONE
+            and self.client_secret_env is not None
+        ):
+            raise ContractValidationError(
+                "'none' cannot be combined with client_secret_env",
+                path=("token_endpoint_auth_method",),
+            )
+        if not 1 <= self.authorization_timeout_seconds <= (1 << 64) - 1:
+            raise ContractValidationError(
+                f"must be greater than zero and less than or equal to {(1 << 64) - 1}",
+                path=("authorization_timeout_seconds",),
+            )
+
+
+@dataclass(slots=True, kw_only=True)
+class McpServiceAccountConfig(ContractModel):
+    """OAuth 2.0 client-credentials authentication for an MCP server."""
+
+    type: Literal["service_account"]
+    client_id: str
+    client_secret_env: str
+    token_url: str
+    scopes: list[str] = _empty_list()
+    token_endpoint_auth_method: OAuthTokenEndpointAuthMethod | None = _optional()
+    token_cache_buffer_seconds: int = _default(300)
+
+    def _validate(self) -> None:
+        for name in ("client_id", "client_secret_env", "token_url"):
+            _nonblank(getattr(self, name), name)
+        _validate_tool_names(self.scopes, "scopes", "authentication scope")
+        if self.token_endpoint_auth_method is OAuthTokenEndpointAuthMethod.NONE:
+            raise ContractValidationError(
+                "service_account requires client_secret_basic or client_secret_post",
+                path=("token_endpoint_auth_method",),
+            )
+        _bounded_int(
+            self.token_cache_buffer_seconds,
+            "token_cache_buffer_seconds",
+            (1 << 64) - 1,
+        )
+
+
+McpAuthenticationConfig = McpOAuth2Config | McpServiceAccountConfig
+
+
 @dataclass(slots=True, kw_only=True)
 class AgentMcpServerConfig(AgentContractBlock):
     """One MCP server routed to the adapter target."""
@@ -218,12 +324,18 @@ class AgentMcpServerConfig(AgentContractBlock):
     url: str
     args: list[str] = _empty_list()
     env: dict[str, str] = _empty_dict()
+    authentication: McpAuthenticationConfig | None = _optional()
+    custom_headers: dict[str, str] = _empty_dict()
     allowed_tools: list[str] | None = _optional()
     blocked_tools: list[str] = _empty_list()
 
     def _validate(self) -> None:
         _nonblank(self.transport, "transport")
         _nonblank(self.url, "url")
+        if self.transport != "stdio" and self.env:
+            raise ContractValidationError(
+                "env is only valid for stdio transport", path=("env",)
+            )
         _validate_tool_names(self.allowed_tools, "allowed_tools", "MCP tool")
         _validate_tool_names(self.blocked_tools, "blocked_tools", "MCP tool")
         if self.allowed_tools is not None: