Connect MCP tools to Managed Deep Agents

Register, connect, and reference MCP tools for Managed Deep Agents.

Managed Deep Agents can call external tools that you expose through the Model Context Protocol (MCP): for example, GitHub, internal services, or third-party APIs. LangSmith manages the connection to each MCP server, including per-user OAuth, so agents authenticate without custom client code.

MCP servers are workspace-level resources. Register or connect a server before you deploy an agent that references it. View all of your MCP servers in LangSmith > Settings > MCP Servers.

Managed Deep Agents is in private preview, available on LangSmith Cloud in the US region only. Join the waitlist to request access.

Prerequisites

• Managed Deep Agents private preview access.
• An MCP server URL, plus any static headers or OAuth credentials the server requires.
• For CLI workflows, deepagents-cli>=0.2.0. Confirm the installed version with deepagents --version. An older deepagents on your PATH can shadow the current release. See the CLI reference for installation.
• For API workflows, a LangSmith API key for a workspace with private preview access.

Quickstart

From a project directory created by deepagents init, connect a static-header tool and deploy:

# 1. Register the MCP server.
deepagents mcp-servers add --url https://example.com/mcp --name my-tools

# 2. List its tools and copy the printed tools.json snippet.
deepagents mcp-servers tools my-tools

# 3. Paste the tool entries into tools.json (manual step).

# 4. Deploy the agent.
deepagents deploy

For an OAuth server, run deepagents mcp-servers connect <id|name|url> after the register step (step 1) and before listing tools (step 2). The following sections cover each step in detail.

Use the CLI for most setups. Use the REST API when you need a custom client, cannot run the CLI from your automation, or want direct control over request payloads.

Connect tools with the CLI

In the CLI, add registers a server and connect completes OAuth for a registered server. For all MCP server commands and flags, see the CLI reference.

Add a static-header MCP server

Register a server:

deepagents mcp-servers add \
  --url https://example.com/mcp \
  --name my-tools

If the server requires static credentials, pass headers:

deepagents mcp-servers add \
  --url https://example.com/mcp \
  --name my-tools \
  --header Authorization="Bearer <token>"

Repeat --header for multiple headers:

deepagents mcp-servers add \
  --url https://example.com/mcp \
  --name my-tools \
  --header Authorization="Bearer <token>" \
  --header X-Workspace-ID="<workspace-id>"

If the CLI can reach the server, it lists the server’s tools after registration and prints a tools.json snippet. To skip that step, pass --no-tools.

Add an OAuth MCP server

Register and connect an OAuth MCP server:

deepagents mcp-servers add \
  --url https://example.com/mcp \
  --name github-tools \
  --auth-type oauth \
  --connect

The command runs the full per-user OAuth flow:

1. Registers the MCP server for per-user OAuth.
2. Prints and opens a verification URL.
3. Waits while you approve access in the browser.
4. Confirms the connection once approval completes.

To connect an OAuth MCP server that already exists, run:

deepagents mcp-servers connect <id|name|url>

Use --scope to request OAuth scopes:

deepagents mcp-servers connect <id|name|url> \
  --scope repo \
  --scope read:user

Use --timeout 0 to start the OAuth flow without polling:

deepagents mcp-servers connect <id|name|url> --timeout 0

When the command starts an authorization session, it prints the verification URL. Re-run deepagents mcp-servers connect <id|name|url> later to complete or reuse the connection.

List available tools

List the tools exposed by a registered MCP server:

deepagents mcp-servers tools <id|name|url>

The command prints each tool name with its first description line, then a tools.json snippet. Copy the entries you want and reference them. Re-run it to refresh entries when a server’s tools change. If no tools are listed, confirm the server URL is reachable and, for OAuth servers, that you completed connect.

Connect tools with the API

Set request defaults

Set the base URL and API key:

export LANGSMITH_API_KEY="<LANGSMITH_API_KEY>"
export LANGSMITH_API_URL="https://api.smith.langchain.com"
export DEEPAGENTS_BASE_URL="$LANGSMITH_API_URL/v1/deepagents"

Requests require the X-Api-Key header:

X-Api-Key: <LANGSMITH_API_KEY>

If a request fails, the API returns a non-2xx status with the error detail in the response body. For authentication errors (401 and 403), see the API reference.

Register a static-header MCP server

Use POST /v1/deepagents/mcp-servers:

Python (httpx)

import os

import httpx

BASE_URL = os.environ["DEEPAGENTS_BASE_URL"]
HEADERS = {"X-Api-Key": os.environ["LANGSMITH_API_KEY"]}

response = httpx.post(
    f"{BASE_URL}/mcp-servers",
    headers=HEADERS,
    json={
        "name": "my-tools",
        "url": "https://example.com/mcp",
        "headers": [
            {"key": "Authorization", "value": "Bearer <token>"},
        ],
    },
)
response.raise_for_status()
print(response.json())

JavaScript (fetch)

const BASE_URL = process.env.DEEPAGENTS_BASE_URL!
const HEADERS = {
  "X-Api-Key": process.env.LANGSMITH_API_KEY!,
  "Content-Type": "application/json",
}

const response = await fetch(`${BASE_URL}/mcp-servers`, {
  method: "POST",
  headers: HEADERS,
  body: JSON.stringify({
    name: "my-tools",
    url: "https://example.com/mcp",
    headers: [{ key: "Authorization", value: "Bearer <token>" }],
  }),
})
if (!response.ok) throw new Error(await response.text())
console.log(await response.json())

cURL

curl --request POST \
  --url "$DEEPAGENTS_BASE_URL/mcp-servers" \
  --header "X-Api-Key: $LANGSMITH_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "my-tools",
    "url": "https://example.com/mcp",
    "headers": [
      {"key": "Authorization", "value": "Bearer <token>"}
    ]
  }'

Register an OAuth MCP server

For an OAuth MCP server, use this route sequence:

1. POST /v1/deepagents/mcp-servers with auth_type=oauth and oauth_mode=per_user_dynamic_client.
2. POST /v1/deepagents/mcp-servers/{mcp_server_id}/oauth-provider.
3. POST /v1/deepagents/auth-sessions.
4. GET /v1/deepagents/auth-sessions/{session_id}, polling until the session status is COMPLETED.

List a server’s tools

List the tools exposed by a registered MCP server with GET /v1/deepagents/mcp/tools. Pass the registered server URL as url. For OAuth servers, also pass the oauth_provider_id returned on the MCP server record. Then reference them.

Reference tools

A tool entry requires name, a tool exposed by a registered MCP server, and mcp_server_url, which points at that server. The mcp_server_name and display_name fields are optional.

{
  "tools": [
    {
      "name": "example_tool",
      "mcp_server_url": "https://example.com/mcp",
      "mcp_server_name": "my-tools",
      "display_name": "example_tool"
    }
  ],
  "interrupt_config": {
    "https://example.com/mcp::example_tool": true
  }
}

With the CLI, add these entries to the tools.json file in your project root. deepagents init scaffolds it with an empty tools array. With the API, send the same object as the tools field of the create-agent or update-agent request body.

Use interrupt_config to require human approval before a tool runs. Key each entry by "{mcp_server_url}::{tool_name}" and set it to true. You can also include the server name in the key: "{mcp_server_url}::{mcp_server_name}::{tool_name}". When an agent calls a tool marked for approval, the run pauses with an interrupt that an operator resolves with the resolve-interrupt route.

To deploy an agent with no MCP tools, leave tools.json empty or omit the tools field.

Validate tools at deploy time

At deploy time, Managed Deep Agents validates the referenced MCP server URLs:

• If a server URL is not registered, register it first. CLI: deepagents mcp-servers add. API: POST /v1/deepagents/mcp-servers.
• If an OAuth server is registered but the caller cannot invoke it, complete OAuth first. CLI: deepagents mcp-servers connect <id|name|url>. API: run the OAuth auth-session flow.

The CLI runs this check locally before it sends the deploy request.

Manage server credentials

Static headers are stored with the MCP server record and are redacted whenever you inspect it.

Task	CLI	API
Inspect a server (headers redacted)	deepagents mcp-servers get <server>	GET /v1/deepagents/mcp-servers/{mcp_server_id}
Change headers	deepagents mcp-servers update <server>	PATCH /v1/deepagents/mcp-servers/{mcp_server_id}
Remove a server and its stored headers	deepagents mcp-servers delete <server>	DELETE /v1/deepagents/mcp-servers/{mcp_server_id}

For OAuth servers, credentials are scoped per user, so each caller completes their own connection. For the full command list, see the CLI reference. For all MCP server routes, see the API reference.

Next steps

After you connect tools, deploy the agent with a tools.json file that references the registered MCP server URLs.

---

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

Edit this page on GitHub or file an issue.