managed-deepagents 0.6.2.dev53__py3-none-win_amd64.whl → 0.6.2.dev55__py3-none-win_amd64.whl

managed_deepagents/__init__.py

@@ -8,7 +8,7 @@ This package provides two things:
   ``mda`` console script.
 
 Resources use ``define_*`` factories while provider collections use namespaces:
-``define_sandbox()``, ``channels.slack(...)``, ``connectors.mcp(...)``,
+``define_sandbox()``, ``define_mcp()``, ``channels.slack(...)``,
 ``connections.get(...)``, and ``auth.supabase(...)``. Contributing a *new*
 primitive is not part of the public surface.
 """
@@ -32,6 +32,7 @@ from managed_deepagents.namespaces import (
     auth,
     channels,
     connectors,
+    define_mcp,
     define_sandbox,
 )
 from managed_deepagents.sandbox import SandboxDefinition
@@ -53,6 +54,7 @@ __all__ = [
     "connectors",
     "define_deep_agent",
     "define_identity",
+    "define_mcp",
     "define_memory",
     "define_sandbox",
     "define_schedule",

managed_deepagents/_agent_auth.py

@@ -95,8 +95,8 @@ class WorkspaceConnection:
 class CredentialAuthorizationRequiredError(RuntimeError):
     def __init__(self, slugs: list[str]) -> None:
         super().__init__(
-            f"the caller has not connected: {', '.join(slugs)}. Declare the connection "
-            "on a connector so the pre-run gate can request it."
+            f"the caller has not connected: {', '.join(slugs)}. "
+            "The authorization interrupt resumed without a usable credential."
         )
         self.slugs = slugs
 
@@ -309,9 +309,14 @@ class AgentAuth:
             return None
         return self.read_secret(credential_id)
 
-    def read_connection_access_token(self, connection_id: str) -> str | None:
-        """Read an OAuth access token stored on a workspace connection row."""
-        return self._fetch_access_token(connection_id)
+    def read_agent_access_token_for_connection(self, connection: WorkspaceConnection) -> str | None:
+        """Read this deployment's OAuth grant for a workspace connection."""
+        agent_id = (self.context.agent_id or "").strip()
+        if not agent_id:
+            raise CredentialStoreError(
+                "connections are not configured: LANGSMITH_HOST_PROJECT_ID is not set"
+            )
+        return self._read_access_token_for_owner(connection, "agent", agent_id)
 
     def read_user_access_token(self, slug: str) -> str | None:
         """Read the caller's OAuth access token without starting a session.
@@ -330,10 +335,18 @@ class AgentAuth:
 
     def read_user_access_token_for_connection(self, connection: WorkspaceConnection) -> str | None:
         """Read a caller OAuth token when the connection row is already loaded."""
+        return self._read_access_token_for_owner(connection, "user", self.context.principal_id)
+
+    def _read_access_token_for_owner(
+        self,
+        connection: WorkspaceConnection,
+        owner_type: str,
+        owner_id: str,
+    ) -> str | None:
         if connection.kind != "oauth2":
             return None
         credential_id = self._credential_id_for_owner(
-            connection.connection_id, "user", self.context.principal_id
+            connection.connection_id, owner_type, owner_id
         )
         if credential_id is None:
             return None

managed_deepagents/_connection_authorization.py

@@ -0,0 +1,96 @@
+"""Resolve user-owned connections or interrupt for authorization."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from importlib import import_module
+from typing import Literal, TypedDict, cast
+
+from managed_deepagents._agent_auth import (
+    AgentAuth,
+    CredentialAuthorizationRequiredError,
+)
+from managed_deepagents._agent_auth_http import CredentialStoreError
+
+
+class PendingCredential(TypedDict, total=False):
+    slug: str
+    kind: Literal["oauth2", "secret"]
+    connect_url: str
+    auth_id: str
+
+
+class CredentialAuthorizationRequiredInterrupt(TypedDict):
+    """Interrupt payload when the caller has not granted one or more connections."""
+
+    type: str
+    message: str
+    credentials: list[PendingCredential]
+
+
+@dataclass(frozen=True)
+class _UserConnectionGrant:
+    slug: str
+    kind: Literal["oauth2", "secret"]
+    token: str | None
+
+
+InterruptFn = Callable[[CredentialAuthorizationRequiredInterrupt], None]
+
+
+def resolve_user_connection_grants(
+    agent_auth: AgentAuth,
+    slugs: Sequence[str],
+    *,
+    interrupt: InterruptFn | None = None,
+) -> dict[str, str]:
+    """Return user connection material or interrupt once for every missing grant."""
+    grants = [_read_user_connection_grant(agent_auth, slug) for slug in dict.fromkeys(slugs)]
+    missing_oauth = [grant for grant in grants if grant.token is None and grant.kind == "oauth2"]
+    missing_secret = [grant for grant in grants if grant.token is None and grant.kind == "secret"]
+    if missing_oauth or missing_secret:
+        sessions = [agent_auth.start_authorization_session(grant.slug) for grant in missing_oauth]
+        payload: CredentialAuthorizationRequiredInterrupt = {
+            "type": "credential_authorization_required",
+            "message": "Connect the following integrations to continue.",
+            "credentials": [
+                {
+                    "slug": session["slug"],
+                    "kind": "oauth2",
+                    "connect_url": session["connect_url"],
+                    "auth_id": session["auth_id"],
+                }
+                for session in sessions
+            ]
+            + [{"slug": grant.slug, "kind": "secret"} for grant in missing_secret],
+        }
+        (interrupt or _interrupt)(payload)
+        raise CredentialAuthorizationRequiredError(
+            [grant.slug for grant in missing_oauth] + [grant.slug for grant in missing_secret]
+        )
+    return {grant.slug: cast("str", grant.token) for grant in grants}
+
+
+def _read_user_connection_grant(agent_auth: AgentAuth, slug: str) -> _UserConnectionGrant:
+    row = agent_auth.find_workspace_connection(slug)
+    if row is None:
+        raise CredentialStoreError(f"workspace connection {slug!r} is not configured")
+    kind: Literal["oauth2", "secret"] = "secret" if row.kind == "secret" else "oauth2"
+    token = (
+        agent_auth.read_user_secret_for_connection(row)
+        if kind == "secret"
+        else agent_auth.read_user_access_token_for_connection(row)
+    )
+    return _UserConnectionGrant(slug=slug, kind=kind, token=token)
+
+
+def _interrupt(payload: CredentialAuthorizationRequiredInterrupt) -> None:
+    import_module("langgraph.types").interrupt(payload)
+
+
+__all__ = [
+    "CredentialAuthorizationRequiredInterrupt",
+    "PendingCredential",
+    "resolve_user_connection_grants",
+]

managed_deepagents/_connections.py

@@ -6,7 +6,9 @@ reads Agent Auth on every await and never caches material.
 
 ``mda dev`` substitutes local values for agent opaque secrets via ``MDA_DEV_*``.
 User-owned connections talk to Agent Auth in every environment (including
-``mda dev``) after resolving the caller's Agent Auth principal.
+``mda dev``) after resolving the caller's Agent Auth principal. Missing grants
+interrupt at the point of access, including calls from custom tools and
+middleware.
 """
 
 from __future__ import annotations
@@ -253,25 +255,18 @@ def _lookup_workspace_connection(
     slug: str,
     owner: ConnectionOwner,
 ) -> str | None:
+    if owner["type"] == "user":
+        from managed_deepagents._connection_authorization import (  # noqa: PLC0415
+            resolve_user_connection_grants,
+        )
+
+        return resolve_user_connection_grants(client, [slug])[slug]
     row = client.find_workspace_connection(slug)
     if row is None:
         return None
-    if owner["type"] == "user":
-        return _lookup_user_connection_material(client, row)
     return _lookup_agent_connection_material(client, slug, row)
 
 
-def _lookup_user_connection_material(
-    client: AgentAuth,
-    row: WorkspaceConnection,
-) -> str | None:
-    if row.kind == "secret":
-        return client.read_user_secret_for_connection(row)
-    if row.kind == "oauth2":
-        return client.read_user_access_token_for_connection(row)
-    return None
-
-
 def _lookup_agent_connection_material(
     client: AgentAuth,
     slug: str,
@@ -283,7 +278,7 @@ def _lookup_agent_connection_material(
             return None
         return client.read_secret(credential_id)
     if row.kind == "oauth2":
-        return client.read_connection_access_token(row.connection_id)
+        return client.read_agent_access_token_for_connection(row)
     return None
 
 

managed_deepagents/_connectors/__init__.py

@@ -4,9 +4,8 @@ First-party connectors each live in their own subpackage:
 
 - :mod:`managed_deepagents._connectors.mcp` — MCP tools
 
-A project selects them through the ``connectors`` namespace
-(``connectors.mcp(...)``); the compiler discovers the result by shape (a
-module-level ``connector`` attribute), not by filename.
+A project selects them with ``define_mcp(...)``; the compiler discovers the
+result by shape (a module-level ``connector`` attribute), not by filename.
 """
 
 from __future__ import annotations

managed_deepagents/_connectors/mcp/__init__.py

@@ -1,6 +1,6 @@
-"""MCP connector authoring surface for the Python ecosystem.
+"""MCP authoring surface for the Python ecosystem.
 
-``connectors.mcp`` implements the ``tools`` hook. Only remote MCP servers over
+``define_mcp`` implements the ``tools`` hook. Only remote MCP servers over
 HTTP/SSE are supported; stdio is intentionally out of scope. By default, all
 tools loaded from each declared server are exposed. Use ``include_tools`` or
 ``exclude_tools`` inside a server config to select a subset by raw MCP tool
@@ -8,14 +8,14 @@ name, before any managed ``{server}__`` prefix is applied.
 
 Example::
 
-    # connectors/mcp.py
-    from managed_deepagents import connectors, connections
+    # tools/mcp.py
+    from managed_deepagents import define_mcp, connections
 
-    connector = connectors.mcp(
+    mcp = define_mcp(
         use_standard_content_blocks=True,
         prefix_tool_name_with_server_name=True,
         throw_on_load_error=True,
-        mcp_servers={
+        servers={
             "docs": {
                 "transport": "http",
                 "url": "https://docs.example.com/mcp",
@@ -89,25 +89,33 @@ class SseMcpServerConfig(RemoteMcpServerBaseConfig, total=False):
 RemoteMcpServerConfig = HttpMcpServerConfig | SseMcpServerConfig
 
 
-class McpServersConfigRequired(TypedDict):
-    mcp_servers: dict[str, RemoteMcpServerConfig]
-
-
-class McpServersConfig(McpServersConfigRequired, total=False):
+class McpServersConfigOptions(TypedDict, total=False):
     prefix_tool_name_with_server_name: bool
     throw_on_load_error: bool
     use_standard_content_blocks: bool
     on_connection_error: Literal["throw"]
 
 
-__all__ = ["McpServersConfig", "McpServersDefinition", "mcp_connector"]
+class McpServersConfigRequired(McpServersConfigOptions):
+    servers: dict[str, RemoteMcpServerConfig]
+
+
+class McpServersConfigLegacy(McpServersConfigOptions):
+    #: Deprecated alias of ``servers``. Removed in 0.8.0.
+    mcp_servers: dict[str, RemoteMcpServerConfig]
+
+
+McpServersConfig = McpServersConfigRequired | McpServersConfigLegacy
+
+
+__all__ = ["McpServersConfig", "McpServersDefinition", "define_mcp"]
 
 #: Remote transports MDA supports. Stdio is intentionally unsupported in v0.
 _REMOTE_TRANSPORTS = ("http", "sse")
 
 
 class McpServersDefinition(Connector):
-    """The MCP connector returned by ``connectors.mcp(...)``.
+    """The MCP connector returned by ``define_mcp(...)``.
 
     A branded managed :class:`Connector` whose ``tools`` hook loads the declared
     MCP tools at runtime; MDA's generated entry hands it to the managed runtime,
@@ -117,7 +125,8 @@ class McpServersDefinition(Connector):
     kind = "mcp_servers"
 
     def __init__(self, **config: Any) -> None:
-        self.config = cast("McpServersConfig", config)
+        # The argument model rewrites the legacy key before construction.
+        self.config = cast("McpServersConfigRequired", config)
 
     def tools(self, ctx: Mapping[str, object] | None = None) -> Sequence[object]:  # noqa: ARG002
         """Load (and cache) the declared MCP tools."""
@@ -127,7 +136,7 @@ class McpServersDefinition(Connector):
         """Describe user and agent connections that deploy must validate."""
         user_slugs: set[str] = set()
         agent_slugs: set[str] = set()
-        for server in self.config["mcp_servers"].values():
+        for server in self.config["servers"].values():
             connection = server.get("connection") if isinstance(server, dict) else None
             if not is_connection_reference(connection):
                 continue
@@ -148,7 +157,7 @@ class McpServersDefinition(Connector):
         }
 
     def __repr__(self) -> str:  # pragma: no cover - debug helper
-        servers = ", ".join(sorted(self.config.get("mcp_servers", {})))
+        servers = ", ".join(sorted(self.config.get("servers", {})))
         return f"McpServersDefinition(servers=[{servers}])"
 
 
@@ -165,6 +174,12 @@ _CREDENTIAL_FIELD_DEPRECATION = (
 
 _CREDENTIAL_FIELD_CONFLICT = 'use either "connection" or "credential", not both'
 
+_MCP_SERVERS_KEY_DEPRECATION = (
+    "mcp_servers is deprecated; use servers instead. It will be removed in 0.8.0."
+)
+
+_SERVERS_KEY_CONFLICT = 'use either "servers" or "mcp_servers", not both'
+
 
 def _non_empty_tool_name(name: str) -> str:
     if not name.strip():
@@ -275,13 +290,29 @@ class _McpServersArgs(BaseModel):
 
     model_config = ConfigDict(extra="forbid")
 
-    mcp_servers: dict[str, _RemoteMcpServer]
+    servers: dict[str, _RemoteMcpServer]
     prefix_tool_name_with_server_name: StrictBool = True
     throw_on_load_error: StrictBool = True
     use_standard_content_blocks: StrictBool = True
     on_connection_error: str = "throw"
 
-    @field_validator("mcp_servers")
+    @model_validator(mode="before")
+    @classmethod
+    def _normalize_servers_key(cls, data: Any) -> Any:
+        if not isinstance(data, Mapping):
+            return data
+        has_servers = "servers" in data
+        has_legacy = "mcp_servers" in data
+        if has_servers and has_legacy:
+            raise ValueError(_SERVERS_KEY_CONFLICT)
+        if has_legacy:
+            warnings.warn(_MCP_SERVERS_KEY_DEPRECATION, FutureWarning, stacklevel=2)
+            normalized = dict(data)
+            normalized["servers"] = normalized.pop("mcp_servers")
+            return normalized
+        return data
+
+    @field_validator("servers")
     @classmethod
     def _at_least_one_server(
         cls, servers: dict[str, _RemoteMcpServer]
@@ -308,9 +339,9 @@ class _McpServersArgs(BaseModel):
 
 
 #: Declare the MCP servers whose tools should be loaded into the agent.
-mcp_connector = define_extension(
+define_mcp = define_extension(
     "connector",
-    label="connectors.mcp",
+    label="define_mcp",
     connector=McpServersDefinition,
     args=_McpServersArgs,
 )

managed_deepagents/_connectors/mcp/load.py

@@ -1,7 +1,7 @@
 """Managed connector loaders (MCP tool loading for the managed runtime).
 
 Mirrors the TypeScript ``connectors/mcp/load`` module. Kept separate from
-``runtime.py`` so the authoring ``connectors`` package can delegate MCP loading
+``runtime.py`` so the authoring MCP factory can delegate loading
 without importing the full managed runtime seam.
 """
 
@@ -55,7 +55,7 @@ class _TimedTool(Protocol):
 #: every invocation, but each connector's MCP connection and tool surface are
 #: stable for the life of the deployment — so the client is created and its
 #: tools loaded once per declaration, and every subsequent run reuses them.
-#: Multiple ``connectors.mcp(...)`` modules each get their own entry (keyed by
+#: Multiple ``define_mcp(...)`` modules each get their own entry (keyed by
 #: object identity).
 #:
 #: An agent-owned connection is read into this cache once, so rotating that
@@ -115,7 +115,7 @@ def _user_connection_references(
 ) -> tuple[ConnectionReference, ...]:
     """The declared references themselves: the gate checks their owner."""
     config = getattr(connectors, "config", None)
-    servers = config.get("mcp_servers") if isinstance(config, Mapping) else None
+    servers = config.get("servers") if isinstance(config, Mapping) else None
     if not isinstance(servers, Mapping):
         return ()
     by_slug: dict[str, ConnectionReference] = {}
@@ -137,7 +137,7 @@ def load_user_connection_mcp_tools(
     and holds no transport, so there is nothing to close afterwards.
     """
     config = connectors.config
-    servers = config["mcp_servers"]
+    servers = config["servers"]
     _eager, user_connection = _partition_mcp_servers(servers)
     if not user_connection:
         return []
@@ -218,7 +218,7 @@ def _create_client_and_load_tools(connectors: McpServersDefinition) -> list[obje
     per caller after grants exist.
     """
     config = connectors.config
-    servers = config["mcp_servers"]
+    servers = config["servers"]
     eager, user_connection = _partition_mcp_servers(servers)
     if user_connection:
         _warn_deferred_user_connection_servers(user_connection)

managed_deepagents/_connectors/tool_selection.py

@@ -1,6 +1,6 @@
 """Tool-name selection, shared by the connectors that load tools over MCP.
 
-``connectors.mcp`` selects by raw tool name across arbitrary servers. A name in
+``define_mcp`` selects by raw tool name across arbitrary servers. A name in
 ``include_tools``/``exclude_tools`` that no loaded tool answers to is an error
 naming what *was* available, so a typo fails the deployment instead of silently
 dropping a tool the agent was meant to have.

managed_deepagents/_credential_gate.py

@@ -14,14 +14,16 @@ import time
 from collections.abc import Awaitable, Callable, Mapping, Sequence
 from dataclasses import dataclass, field
 from importlib import import_module
-from typing import TYPE_CHECKING, Any, Literal, TypedDict, cast
+from typing import TYPE_CHECKING, Any, cast
 
 from managed_deepagents._agent_auth import (
     AgentAuth,
     AgentAuthContext,
-    CredentialAuthorizationRequiredError,
-    PendingAuthorization,
-    missing_workspace_connection_error,
+)
+from managed_deepagents._connection_authorization import (
+    CredentialAuthorizationRequiredInterrupt,
+    PendingCredential,
+    resolve_user_connection_grants,
 )
 from managed_deepagents._connections import (
     ConnectionReference,
@@ -43,21 +45,6 @@ CREDENTIAL_GATE_MIDDLEWARE_NAME = "mda-credential-gate"
 _TOOL_CACHE_TTL_SECONDS = 5 * 60
 
 
-class PendingCredential(TypedDict, total=False):
-    slug: str
-    kind: Literal["oauth2", "secret"]
-    connect_url: str
-    auth_id: str
-
-
-class CredentialAuthorizationRequiredInterrupt(TypedDict):
-    """Interrupt payload when the caller has not granted one or more connections."""
-
-    type: str
-    message: str
-    credentials: list[PendingCredential]
-
-
 @dataclass(frozen=True)
 class CredentialConsumer:
     """A declaration whose tools are unlocked by user-owned connections."""
@@ -74,13 +61,6 @@ class _CacheEntry:
     declaration: object = field(repr=False)
 
 
-@dataclass(frozen=True)
-class _UserConnectionGrant:
-    slug: str
-    kind: Literal["oauth2", "secret"]
-    token: str | None
-
-
 _tool_cache: dict[tuple[int, str], _CacheEntry] = {}
 _tool_cache_lock = threading.Lock()
 _tool_load_locks: dict[tuple[int, str], threading.Lock] = {}
@@ -102,13 +82,13 @@ def create_credential_gate_middleware(
 
         def before_agent(self, _state: object, runtime: object | None = None) -> None:
             caller = _require_auth_context(runtime)
-            payload = _pending_interrupt(consumers, caller)
-            _gate(consumers, caller.context, payload)
+            _ensure_grants(consumers, caller)
+            _load_all(consumers, caller.context)
 
         async def abefore_agent(self, _state: object, runtime: object | None = None) -> None:
             caller = await asyncio.to_thread(_require_auth_context, runtime)
-            payload = await asyncio.to_thread(_pending_interrupt, consumers, caller)
-            _gate(consumers, caller.context, payload)
+            await asyncio.to_thread(_ensure_grants, consumers, caller)
+            await asyncio.to_thread(_load_all, consumers, caller.context)
 
         def wrap_model_call(self, request: Any, handler: Callable[..., Any]) -> Any:
             return handler(_with_extra_tools(request, _tools_for(consumers, request)))
@@ -131,71 +111,17 @@ def create_credential_gate_middleware(
     return _CredentialGateMiddleware()
 
 
-def _gate(
-    consumers: Sequence[CredentialConsumer],
-    context: AgentAuthContext,
-    payload: CredentialAuthorizationRequiredInterrupt | None,
-) -> None:
-    if payload is not None:
-        _interrupt(payload)
-        slugs = [item["slug"] for item in payload["credentials"]]
-        raise CredentialAuthorizationRequiredError(slugs)
-    _load_all(consumers, context)
-
-
-def _pending_interrupt(
+def _ensure_grants(
     consumers: Sequence[CredentialConsumer],
     caller: _Caller,
-) -> CredentialAuthorizationRequiredInterrupt | None:
+) -> None:
     agent_auth = AgentAuth(caller.context)
-    grants = _read_user_connection_grants(agent_auth, _consumer_credentials(consumers, caller))
-    missing_oauth = [grant for grant in grants if grant.token is None and grant.kind == "oauth2"]
-    missing_secret = [grant for grant in grants if grant.token is None and grant.kind == "secret"]
-    if not missing_oauth and not missing_secret:
-        return None
-
-    pending_oauth = [agent_auth.start_authorization_session(grant.slug) for grant in missing_oauth]
-    credentials: list[PendingCredential] = [
-        _pending_oauth_entry(session) for session in pending_oauth
-    ] + [_pending_secret_entry(grant.slug) for grant in missing_secret]
-    return {
-        "type": "credential_authorization_required",
-        "message": "Connect the following integrations to continue.",
-        "credentials": credentials,
-    }
-
-
-def _pending_oauth_entry(session: PendingAuthorization) -> PendingCredential:
-    return {
-        "slug": session["slug"],
-        "kind": "oauth2",
-        "connect_url": session["connect_url"],
-        "auth_id": session["auth_id"],
-    }
-
-
-def _pending_secret_entry(slug: str) -> PendingCredential:
-    return {"slug": slug, "kind": "secret"}
-
-
-def _read_user_connection_grants(
-    agent_auth: AgentAuth,
-    references: Sequence[ConnectionReference],
-) -> list[_UserConnectionGrant]:
-    grants: list[_UserConnectionGrant] = []
-    for reference in references:
-        slug = reference.slug
-        row = agent_auth.find_workspace_connection(slug)
-        if row is None:
-            raise missing_workspace_connection_error(slug)
-        kind: Literal["oauth2", "secret"] = "secret" if row.kind == "secret" else "oauth2"
-        token = (
-            agent_auth.read_user_secret_for_connection(row)
-            if kind == "secret"
-            else agent_auth.read_user_access_token_for_connection(row)
-        )
-        grants.append(_UserConnectionGrant(slug=slug, kind=kind, token=token))
-    return grants
+    credentials = _consumer_credentials(consumers, caller)
+    resolve_user_connection_grants(
+        agent_auth,
+        [credential.slug for credential in credentials],
+        interrupt=_interrupt,
+    )
 
 
 def _consumer_credentials(
@@ -269,11 +195,11 @@ def _load_tools(
     context: AgentAuthContext,
 ) -> list[object]:
     agent_auth = AgentAuth(context)
-    grants = _read_user_connection_grants(agent_auth, consumer.credentials)
-    missing = [grant.slug for grant in grants if grant.token is None]
-    if missing:
-        raise CredentialAuthorizationRequiredError(missing)
-    access_tokens = {grant.slug: cast("str", grant.token) for grant in grants}
+    access_tokens = resolve_user_connection_grants(
+        agent_auth,
+        [credential.slug for credential in consumer.credentials],
+        interrupt=_interrupt,
+    )
     return list(wrap_tools_with_managed_runtime(consumer.load(access_tokens)))
 
 

managed_deepagents/_extension.py

@@ -1,11 +1,11 @@
 """The contribution API behind the extensible MDA primitives.
 
-``define_extension(kind, ...)`` returns the factory a connector namespace calls,
-such as ``connectors.mcp(...)``. Argument parsing, branding, and manifest
+``define_extension(kind, ...)`` returns the factory a first-party primitive
+calls, such as ``define_mcp(...)``. Argument parsing, branding, and manifest
 stamping are shared.
 
 This module is deliberately absent from the package's public surface. Only the
-first-party namespaces in :mod:`managed_deepagents.namespaces` contribute
+first-party factories in :mod:`managed_deepagents.namespaces` contribute
 connectors, so an agent project cannot mount its own adapter or HTTP route into
 the managed runtime. Opening it up to third-party packages is a later step.
 

managed_deepagents/namespaces.py

@@ -4,7 +4,7 @@ Provider collections use ``<primitive>.<provider>(...)`` namespaces, while
 resources use ``define_*`` factories::
 
     channels.slack(name="Support Bot", description="Answers support questions")
-    connectors.mcp(mcp_servers={...})
+    define_mcp(servers={...})
     define_sandbox(default_timeout=600)
     auth.supabase(project_ref="abc")
 
@@ -14,18 +14,24 @@ contribute its own — :mod:`managed_deepagents._extension` stays internal.
 
 from __future__ import annotations
 
+import warnings
+
 from pydantic import BaseModel, ConfigDict, field_validator
 
 from managed_deepagents._channels.trigger.channel import slack_channel
-from managed_deepagents._connectors.mcp import mcp_connector
+from managed_deepagents._connectors.mcp import McpServersDefinition, define_mcp
 from managed_deepagents.identity import auth
 from managed_deepagents.sandbox import SandboxDefinition, normalize_sandbox_options
 
-__all__ = ["auth", "channels", "connectors", "define_sandbox"]
+__all__ = ["auth", "channels", "connectors", "define_mcp", "define_sandbox"]
+
+_CONNECTORS_MCP_DEPRECATION = (
+    "connectors.mcp(...) is deprecated; use define_mcp(...) instead. It will be removed in 0.8.0."
+)
 
 
 class _Namespace:
-    """A namespace whose providers are attributes, e.g. ``connectors.mcp``.
+    """A namespace whose providers are attributes, e.g. ``channels.slack``.
 
     Subclasses set the providers as class attributes wrapped in
     :func:`staticmethod`, matching how the TypeScript namespaces are plain
@@ -37,23 +43,27 @@ class _Namespace:
         return f"{type(self).__name__.lstrip('_').lower()}({providers})"
 
 
-class _Connectors(_Namespace):
-    """Integrations declared under ``connectors/``.
+class _Channels(_Namespace):
+    """Inbound messaging surfaces (Events ingress + outbound messaging).
 
-    This release ships only remote MCP servers. Authors attach them with
-    ``connectors.mcp(...)`` and supply their own auth (static headers, etc.).
+    Slack ingress through Trigger Server.
     """
 
-    mcp = staticmethod(mcp_connector)
+    slack = staticmethod(slack_channel)
 
 
-class _Channels(_Namespace):
-    """Inbound messaging surfaces (Events ingress + outbound messaging).
+def _deprecated_mcp(**kwargs: object) -> McpServersDefinition:
+    warnings.warn(_CONNECTORS_MCP_DEPRECATION, FutureWarning, stacklevel=2)
+    return define_mcp(**kwargs)
 
-    Slack ingress through Trigger Server.
+
+class _Connectors(_Namespace):
+    """Deprecated MCP namespace. Use :func:`define_mcp` instead.
+
+    ``connectors.mcp`` will be removed in 0.8.0.
     """
 
-    slack = staticmethod(slack_channel)
+    mcp = staticmethod(_deprecated_mcp)
 
 
 class _SandboxRegistryArgs(BaseModel):
@@ -122,5 +132,5 @@ def define_sandbox(
     return SandboxDefinition(normalized)
 
 
-connectors = _Connectors()
 channels = _Channels()
+connectors = _Connectors()

{managed_deepagents-0.6.2.dev53.dist-info → managed_deepagents-0.6.2.dev55.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: managed-deepagents
-Version: 0.6.2.dev53
+Version: 0.6.2.dev55
 Summary: Managed Deep Agents — the define_deep_agent authoring interface plus the CLI that compiles and deploys a code-first Deep Agent repository to a managed LangGraph runtime.
 Author: LangChain
 License: MIT
@@ -178,11 +178,11 @@ my-agent/
   pyproject.toml
   .env                  # local deploy secrets, never committed
   schedules/            # optional managed cron schedules
-  tools/                # optional custom tools
+  tools/                # optional custom tools and MCP declaration
+    mcp.py              # optional MCP server declaration
   middleware/           # optional middleware
   skills/               # optional skills synced to Context Hub
   sandbox/              # LangSmith sandbox (`mda init` includes this; delete to opt out)
-  connectors/mcp.py     # optional MCP server declaration
 ```
 
 The CLI copies your project files into the managed build and generates the entry
@@ -245,19 +245,22 @@ sandbox = define_sandbox(
 Put `GHCR_TOKEN` in the project `.env` or process environment. Its value is
 used only to reconcile the registry and never enters the build or snapshot.
 
-## MCP Connectors
+## MCP Servers
 
-Add `connectors/mcp.py` to attach MCP servers. The file must define a
-module-level `connector`. By default, MDA exposes every tool loaded from each
+Add `tools/mcp.py` to attach MCP servers. The file must define a module-level
+`mcp`. By default, MDA exposes every tool loaded from each
 declared server. In `mda dev`, an agent-owned connection reads from
 `MDA_DEV_<SLUG>` with the slug uppercased and hyphens changed to underscores.
 Hosted deployments resolve workspace connections from Agent Auth:
 
+The old `connectors/mcp.py` file API remains available with a warning during
+`0.7.x`. It will be removed in `0.8.0`.
+
 ```python
-from managed_deepagents import connectors, connections
+from managed_deepagents import define_mcp, connections
 
-connector = connectors.mcp(
-    mcp_servers={
+mcp = define_mcp(
+    servers={
         "langchainDocs": {
             "transport": "http",
             "url": "https://docs.langchain.com/mcp",
@@ -271,14 +274,15 @@ connector = connectors.mcp(
 For this example, set `MDA_DEV_DOCS_TOKEN`.
 
 A user-owned connection — `connections.get(slug, {"type": "user"})` — resolves
-per caller (OAuth or opaque). The runtime maps the verified ingress identity to
-an Agent Auth principal, then the pre-run credential gate interrupts the run
-when a grant is missing. That path works in `mda deploy` and `mda dev` when
-`LANGSMITH_API_KEY` and `LANGSMITH_WORKSPACE_ID` are set and the workspace
-connection rows exist — use a person principal (for example a Supabase JWT),
-not Studio’s synthetic service user. OAuth completes on LangSmith’s platform
-callback URL; the local UI must surface `credential_authorization_required`
-and resume after the user connects.
+per caller (OAuth or opaque). Any runtime access interrupts the run when a grant
+is missing, including access from a custom tool or middleware. Connector
+declarations use the same behavior in a pre-run gate, so all known grants can be
+requested before the first model call. This path works in `mda deploy` and
+`mda dev` when `LANGSMITH_API_KEY` and `LANGSMITH_WORKSPACE_ID` are set and
+the workspace connection rows exist. Use a person principal (for example, a
+Supabase JWT), not Studio’s synthetic service user. OAuth completes on
+LangSmith’s platform callback URL. The local UI must show
+`credential_authorization_required` and resume after the user connects.
 
 Deploy the project first, then provision its connections with
 `mda connections create`. Agent-owned opaque secrets are scoped to that

{managed_deepagents-0.6.2.dev53.dist-info → managed_deepagents-0.6.2.dev55.dist-info}/RECORD

@@ -1,15 +1,16 @@
-managed_deepagents/__init__.py,sha256=RezkpgYxCcywj6_W7Nk3PN9TMBfYyFgIatxGrIeY8V4,1862
+managed_deepagents/__init__.py,sha256=KLkxKBS4uCcJKJr9CGo5GrVjeHHEjF8Wo6aSdWU4KJk,1889
 managed_deepagents/__main__.py,sha256=GcjmqN0Ea5v8OHKMxYToasm3eCX_doSLOlpEzAi1tAw,67
-managed_deepagents/_agent_auth.py,sha256=8QiCiGxYjbk3BTrOeCGVkQTLh6IzTUia18-_Mry9NWI,20018
+managed_deepagents/_agent_auth.py,sha256=SkpbTWNV4jiwbhGGv230l1UTe2PHPbaSswTWqzGxvq0,20524
 managed_deepagents/_agent_auth_http.py,sha256=d-Fg62m-_5qBXj-d9xgfA3KGiPRfs7T2g6Q2nrhCetc,6065
 managed_deepagents/_channel.py,sha256=-Og7QOM1yvV-yeTDOfv2CxXpR2HLY4xdX1bLrIsPi5k,5272
 managed_deepagents/_cli.py,sha256=jVaw2i1ysdRoWziMdPFmRXtKry_baYGRspyzyIeGWoU,1688
-managed_deepagents/_connections.py,sha256=B0mrBbh0dhFxFMkdkYVAM5Q5WaKUcYJryizZh_Hxg3A,19963
+managed_deepagents/_connection_authorization.py,sha256=WCuJ3-58lQIre-bcXspVx28Gzyg8m9F7KUMunk6CtVo,3387
+managed_deepagents/_connections.py,sha256=oJmpqH_keBhc0VaY2mlc5EZlMZv8jDW0eoEcef0o5Bc,19896
 managed_deepagents/_connector.py,sha256=Syp0SRs1oFCUUltIUmZbSNi1Ys_PxObVdiAi-I9GBzs,8040
 managed_deepagents/_cors.py,sha256=V96RPrqewdRWG5RpEMEBnPuRq9_zF8nf4vf99k5dkuI,7597
-managed_deepagents/_credential_gate.py,sha256=VLjSc7k1MoZdMI8juZpdeOK7lYyvbb9OsFZGAhoj6t4,12287
+managed_deepagents/_credential_gate.py,sha256=oeJSmdLoxwzAg28ALqUm4sWeV0sx__9iEKdNIYdccME,9539
 managed_deepagents/_eval_filesystem.py,sha256=1nuD0yn3gh19JrWNocWyPFyeJW42E7Gse3XRWCUSTAA,1399
-managed_deepagents/_extension.py,sha256=x2H1S8inkvTZQ_dr7kq0M8o8rre1FjzCDvMzItw4iyk,5318
+managed_deepagents/_extension.py,sha256=MqCWS4AGxiURPtLlA2y_tWKdRL8Zu1-VZyQ6Q3HDgzc,5315
 managed_deepagents/_identity_auth.py,sha256=mQ-4pVFZRc9uweFqi7LEzAUtzhuz5fcUHVak0LSzz64,33620
 managed_deepagents/_identity_http.py,sha256=aVQfZr7UKQoXF1Dry3p9fzXIj1882sEa668rvhn37i0,16029
 managed_deepagents/_identity_links.py,sha256=Z1H2Seo2KaI-vcdU3_PGM-F06wOz0IQqUP-28wqiQsA,9172
@@ -23,12 +24,12 @@ managed_deepagents/_memory_instructions.py,sha256=lyxKfNuXrWih574gmy3NHhIq_hIpJI
 managed_deepagents/_validated_token.py,sha256=On96IOQTDz1KE_ZZmuTqY8IPw-cJ3J2tXkkmrfyvbB4,18762
 managed_deepagents/define_deep_agent.py,sha256=17VfiiBINyhlqlATHrlJRPihKVlBsDGDP8K4-fxjxU8,5611
 managed_deepagents/define_memory.py,sha256=n7Ya20dWGvwbZOkPIXoa68nTnJie8tpKEkRwfJQt_fU,5036
-managed_deepagents/namespaces.py,sha256=GS76G19-V5Svfpbca-9xhQfJ6vel52jcJyfj6loLt_Y,4199
+managed_deepagents/namespaces.py,sha256=69i9hHAn9_jq76PPb2kPlbEpCbMylXUS5xPRDO89JFo,4461
 managed_deepagents/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
 managed_deepagents/runtime.py,sha256=B4iKTJZD0zXx_MZ09pqQFOkVo07tqJDT3qvOBr-0iOk,65782
 managed_deepagents/sandbox.py,sha256=xlpcWa6CoVX6GKip2nK-0Lw-HBCoFGFYm0r4x9eYwcY,2530
 managed_deepagents/schedules.py,sha256=MtTQN4tlm1NizFDCjZZv_huGfbQx-dj9WP1dIBybCug,5237
-managed_deepagents/_binaries/mda.exe,sha256=AhDKOXxB5if1NeCBHM_BIOMXZjEbmVPLflbDR9g4Tc0,3905536
+managed_deepagents/_binaries/mda.exe,sha256=-FaDHv0r2g4hD7ZocjF5hp_XhuyRgckqRtkSaTRXVC8,3929600
 managed_deepagents/_channels/__init__.py,sha256=Z6eXmzaLxG09DSyJoY_CX34axcsBo9gSJ0G7pRm2D6M,1216
 managed_deepagents/_channels/assistant_text.py,sha256=f-Z3J3PlQFXZHztgBxlRoqB2LigU1Hj1YpwoXBMTR18,2171
 managed_deepagents/_channels/binding.py,sha256=6vAKbWpg-eyLErJ0SsozH4mZc50hA1NhquM63mVmWDQ,3423
@@ -53,10 +54,10 @@ managed_deepagents/_channels/trigger/client.py,sha256=cM97gzYWUTFC9o3uoveFe9-HxZ
 managed_deepagents/_channels/trigger/http.py,sha256=75ROtdT7PacKAFa-KFFRPATkHDgC7Pu48AUcipTYXY0,16903
 managed_deepagents/_channels/trigger/identity_context.py,sha256=oo6sgtNDLGGkZCzrkrifMHkkAqxj7ui2HgUUdjNA1iU,7701
 managed_deepagents/_channels/trigger/types.py,sha256=9nlArhLf-KgYidxwzrtBVjcpPlV6ytriPX3lJvPR3fE,6746
-managed_deepagents/_connectors/__init__.py,sha256=c_SdH3T7T6bgX7-I5jxAqDzHojmqVUCX0AXRI7g5Ovs,575
-managed_deepagents/_connectors/tool_selection.py,sha256=xMvohEvg_rguQvziUXzxKn4V140mmearZHel97F8tVs,2978
-managed_deepagents/_connectors/mcp/__init__.py,sha256=3AL429g5djYEYuiuSqsxj2VESpTkyU2NeBIJsHlWVk4,11162
-managed_deepagents/_connectors/mcp/load.py,sha256=4gHGQYwC8rfC_7b0YUtQ2tFYJWzzcKiFm1vz6wqDdV0,14696
+managed_deepagents/_connectors/__init__.py,sha256=Ei-DvDmA-F2Bord6WuM7UtWtnuVt3u7CRSPKFqpHFhA,537
+managed_deepagents/_connectors/tool_selection.py,sha256=wHA8TJqsnEw2KIzxN7JpdkD_myh8_yFI0T7Ab349_q4,2974
+managed_deepagents/_connectors/mcp/__init__.py,sha256=uzGndgDbyMD5bKl2o5EYwBTgNcTkymOOitHr4rMdddc,12222
+managed_deepagents/_connectors/mcp/load.py,sha256=Gim2WN-hNUXF3vNfpffnGxuDIA6CXCV7qhZ5TG5Tf7c,14665
 managed_deepagents/_memory/__init__.py,sha256=el08UQseoWgsscuE3h5_ygar0kKfwvBMFqgFLq8F3Ug,268
 managed_deepagents/_memory/async_util.py,sha256=SXre1vvF11-v9G1L6m45xb2fDIWsa08qPxFQ0MGwIgE,1463
 managed_deepagents/_memory/context_io.py,sha256=Ez3K0PH1tjlcHn3-s44JhyDjf1NvDnvbmcNiRd6Pqpc,1621
@@ -69,9 +70,9 @@ managed_deepagents/identity/__init__.py,sha256=RKuFKCN3Ui2ggUzdntYhnEdZRf-vT1khU
 managed_deepagents/identity/claims.py,sha256=prby7r_8Lww3MmoBm8PX6PsSGE3GwSHkr8mVIz_08nU,1180
 managed_deepagents/identity/options.py,sha256=x_yMbXEFR7zXyehEjDHG2qjAlukXjrRBcQLcM6IndLM,2550
 managed_deepagents/identity/supabase.py,sha256=8uobl3WCrQL_ieSXG8KTLf1th7Qjim9liZT50HeaJE0,6026
-managed_deepagents-0.6.2.dev53.dist-info/licenses/LICENSE,sha256=WnPZQQ608ojZUkXl7BW6VbKloIAibZiGm1K6cjeZOL8,1066
-managed_deepagents-0.6.2.dev53.dist-info/METADATA,sha256=Rb-W6mSRGEnhbHjpyI69y5hgBuO04EOxyxdcPNTHCpg,13690
-managed_deepagents-0.6.2.dev53.dist-info/WHEEL,sha256=3I5VVWZdsFlU417aCS2bMRuerS8wsfvBq99MyatBV3A,97
-managed_deepagents-0.6.2.dev53.dist-info/entry_points.txt,sha256=ziZqkKuaDO3qHCjKmBhrx9cm3ok8bZ9xcEDpUTj4unM,53
-managed_deepagents-0.6.2.dev53.dist-info/top_level.txt,sha256=fdBo4O0Hlol_w022tTLB5ftZpamb4yJoQ3MUvjgTGfA,19
-managed_deepagents-0.6.2.dev53.dist-info/RECORD,,
+managed_deepagents-0.6.2.dev55.dist-info/licenses/LICENSE,sha256=WnPZQQ608ojZUkXl7BW6VbKloIAibZiGm1K6cjeZOL8,1066
+managed_deepagents-0.6.2.dev55.dist-info/METADATA,sha256=atyu0CKHLYl_3TFm1yHep-LQJkh59vMs1J_2xw37kU4,13887
+managed_deepagents-0.6.2.dev55.dist-info/WHEEL,sha256=3I5VVWZdsFlU417aCS2bMRuerS8wsfvBq99MyatBV3A,97
+managed_deepagents-0.6.2.dev55.dist-info/entry_points.txt,sha256=ziZqkKuaDO3qHCjKmBhrx9cm3ok8bZ9xcEDpUTj4unM,53
+managed_deepagents-0.6.2.dev55.dist-info/top_level.txt,sha256=fdBo4O0Hlol_w022tTLB5ftZpamb4yJoQ3MUvjgTGfA,19
+managed_deepagents-0.6.2.dev55.dist-info/RECORD,,