Connect to MCP servers

Connect a managed deep agent to remote Model Context Protocol (MCP) servers to add their tools to the agent. Managed Deep Agents creates the MCP client and loads the tools. Most remote MCP servers require authentication. A connection supplies it, and declaring the connection as user-owned makes each caller authorize their own account.

Managed Deep Agents is in public beta and available on LangSmith Cloud in the US region only.

Declare MCP servers in a module directly under tools/:

my-agent/
  agent.ts
  tools/
    mcp.ts

For the full project layout, see Project structure. To implement application logic in the project instead, use an authored tool.

Add an MCP servers

Use an MCP server when tools already live on a remote MCP server and you want MDA to load them without importing them into the agent definition.

Declare the connector

Use connectors.mcp to declare one or more remote servers:Use defineMcp to declare one or more remote servers:

tools/mcp.ts

import { defineMcp } from "managed-deepagents";

export const mcp = defineMcp({
  servers: {
    langchainDocs: {
      transport: "http",
      url: "https://docs.langchain.com/mcp",
    },
  },
});

The module must export a named connector.Managed Deep Agents supports Streamable HTTP ("http") and legacy SSE ("sse") transports. Stdio MCP servers are not supported. Expose a stdio server over HTTP or implement its operation as an authored tool instead.For connection options, see Manage connections.

Select tools (Optional)

By default, Managed Deep Agents exposes every tool from each server. To expose only selected tools, set an allowlist inside that server’s configuration:

{
  transport: "http",
  url: "https://docs.langchain.com/mcp",
  includeTools: ["search_docs_by_lang_chain"],
}

To expose every tool except selected tools, replace includeTools with excludeTools.You can use both options together. The denylist applies after the allowlist, and the same tool cannot appear in both lists.Selection uses raw MCP tool names before Managed Deep Agents prefixes them. Tool names are prefixed with the server name by default to avoid collisions. For example, the search_docs_by_lang_chain tool from the langchainDocs server is exposed as langchainDocs__search_docs_by_lang_chain.

Pass credentials (Optional)

If an MCP server requires credentials, declare a connection on the server config and create that connection in the workspace.

MCP OAuth: For servers that advertise OAuth and support automatic client registration, create with mda connections create <slug> (inferred from the MCP declaration) or mda connections create <slug> --mcp <url>. You do not supply a client ID or secret.
Opaque secret or general OAuth: For a static API key, or for a BYOT OAuth app you register yourself, create an opaque secret or general OAuth connection, then set the server’s connection option to connections.get(...).

For create modes, owners, and runtime authorization, see Manage connections.

Configure MCP servers

Each server supports the following core options:

Option	Description
`transport`	Required. Use `http` for Streamable HTTP or `sse` for legacy SSE.
`url`	Required. The remote MCP endpoint URL.
`headers`	Static headers to send to the server.
`include_tools` / `includeTools`	Raw MCP tool names to expose.
`exclude_tools` / `excludeTools`	Raw MCP tool names to hide.
`default_tool_timeout` / `defaultToolTimeout`	Timeout for each tool call, in seconds for Python and milliseconds for TypeScript.
`automatic_sse_fallback` / `automaticSSEFallback`	For HTTP, allow the client to fall back to SSE.
`reconnect`	For SSE, configure reconnection behavior.

The MCP definition also accepts these options:

Option	Default	Description
`prefix_tool_name_with_server_name` / `prefixToolNameWithServerName`	`true`	Prefix each tool with `{server}__`.
`throw_on_load_error` / `throwOnLoadError`	`true`	Fail loading instead of starting with a partial tool set.

Deployment

mda dev and mda deploy discover connector modules under connectors/ and include them in the managed configuration. Connectors are not synced to Context Hub.

When to use MCP connectors

Concept	Kind	How it reaches the agent
MCP servers	Managed configuration	Declared under `tools/`; no import into the agent entry
MCP endpoint	Deployment API	Exposes the agent as a tool to MCP clients
Authored tools	Application code	Import and pass in the agent definition
Channels	Managed configuration	Receive external messages that start agent runs and deliver responses

For more information, see Project structure.

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

Get started

Agent capabilities

Build and deploy

Add an MCP servers

Configure MCP servers

Deployment

When to use MCP connectors

​Add an MCP servers

​Configure MCP servers

​Deployment

​When to use MCP connectors

Add an MCP servers

Configure MCP servers

Deployment

When to use MCP connectors