docs(mda): update to with CLI experience and mcp oauth capability

[Victor Moreira (victorm-lc)]

Overview

Reconciles the Managed Deep Agents documentation with the actual behavior of the deepagents deploy CLI (0.2.0) after running the flow end to end. The headline fix: the guide documented referencing MCP servers via agent.json tools.mcp_servers, a shape that exists in neither the CLI nor the OpenAPI spec — following it deploys an agent with no tools. This PR makes tools.json the canonical, documented path and corrects several other mismatches.

Changes to src/langsmith/deploy-managed-deep-agent.mdx:

• Reference MCP servers: removed the non-working agent.json tools.mcp_servers example; tools.json (tools[].mcp_server_url) is now the single documented mechanism, with the correct interrupt_config key format ({mcp_server_url}::{tool_name}::{mcp_server_name}: true).
• Create-a-project flow: added an explicit step to register the MCP server and add tools.json before deploy (since deepagents init does not scaffold it).
• Scaffold table: reframed tools.json from "advanced compatibility" to the actual tool-configuration file.
• Deploy section: documented the real success output (agent_id, revision, agent URL, and the MCP health check) and noted that every deploy creates a new agent
  revision even when managed files are unchanged.
• Agent limits: corrected the quota section — free workspaces are capped at 1 Managed Deep Agent (HTTP 409 on overflow); paid plans are unlimited (previously stated there were no per-workspace limits).
• Install: added a note that a previously installed stable deepagents can shadow the beta on PATH (verify with deepagents --version).

src/langsmith/managed-deep-agents-api.mdx: added "agent limits" to the operational
topics it defers to the deploy guide. The OpenAPI spec was already correct and is
unchanged.

Type of change

Type: Update existing documentation

Related issues/PRs

• Feature PR: feat(cli): migrate deepagents deploy to use managed deep agents api [AB-2470] deepagents#3609
• Linear issue: https://linear.app/langchain/issue/AB-2470/mda-wrap-apis-in-deepagents-deploy and https://linear.app/langchain/issue/AB-2485/mda-enable-oauth-on-mcp-servers

Checklist

• I have read the contributing guidelines, including the language policy
• I have tested my changes locally using docs dev
• All code examples have been tested and work correctly
• I have used root relative paths for internal links
• I have updated navigation in src/docs.json if needed

Additional notes

All edits were verified against the shipping CLI: markdownlint reports no new warnings (pre-existing MD046 hits are in untouched REST <Tab> examples), make check-cross-refs passes, and every JSON snippet parses. The documented tools.json shape was confirmed by running deepagents deploy --dry-run and checking the emitted payload contains the tools key — the exact check that exposed the original bug. No new pages were added, so src/docs.json needs no changes.

One follow-up worth flagging: confirm with the backend team whether the bare tool-name interrupt_config form is honored at runtime, or only the {url}::{tool}::{server} key format documented here.

[github-actions]

Thanks for opening a docs PR, Victor Moreira (@victorm-lc)! When it's ready for review, please add the relevant reviewers:

• @katmayb or @fjmorris (LangSmith)

[github-actions]

Mintlify preview branch generated: preview-vicmda-1780088974-0fb0763

Site preview: https://langchain-5e9cc07a-preview-vicmda-1780088974-0fb0763.mintlify.app

Preview links may take a few minutes to start working while the deployment finishes.

Changed documentation pages (preview deep links):

• src/langsmith/deploy-managed-deep-agent.mdx
• src/langsmith/managed-deep-agents-api.mdx