Register an MCP server

Register an MCP server in the caller’s workspace. Static-header servers can include credential headers. OAuth servers should set auth_type=oauth and oauth_mode=per_user_dynamic_client, then register an OAuth provider and start an auth session before use.

POST /mcp-servers

cURL

basic

curl --request POST \ --url https://api.smith.langchain.com/v1/deepagents/mcp-servers \ --header 'Content-Type: application/json' \ --header 'X-Api-Key: <api-key>' \ --data ' { "name": "tavily", "url": "https://mcp.tavily.com/mcp/", "headers": [ { "key": "Authorization", "value": "Bearer tvly-..." } ] } '

201

basic

{ "id": "5b6f6a2b-2c95-4f0f-9c2b-7c3a3e4f8d11", "tenant_id": "33499cf9-4c02-49af-909d-b8f42e051eab", "name": "tavily", "url": "https://mcp.tavily.com/mcp/", "headers": [ { "key": "Authorization", "value": "Bearer tvly-..." } ], "auth_type": "", "oauth_mode": "", "created_at": "2026-05-20T20:50:32.708302+00:00", "updated_at": "2026-05-20T20:50:32.708302+00:00", "mcp_vendor_id": null, "vendor_id": null, "external_system_id": null }

Authorizations

X-Api-Key · string · header · default: LANGSMITH_API_KEY · required

Body

application/json

name · string · required

Human-readable name for the MCP server.

url · string<uri> · required

MCP server URL. Must be a valid HTTPS endpoint.

headers · object[]

Credential headers attached to every invocation of this MCP server. Omitted from response bodies when the caller lacks invoke permission on the server.

Show child attributes

auth_type · enum<string>

Authentication scheme used by the MCP server.

Available options: headers, oauth

oauth_provider_id · string<uuid> | null

Optional OAuth provider ID for legacy shared OAuth providers.

oauth_mode · enum<string>

OAuth mode used by an OAuth MCP server.

Available options: legacy_shared_provider, per_user_dynamic_client

vendor_id · string

Optional vendor identifier for catalog grouping.

external_system_id · string

Optional opaque external system identifier.

Response

201

application/json

MCP server registered.

id · string<uuid>

tenant_id · string<uuid>

name · string

url · string<uri>

headers · object[]

Credential headers attached to every invocation of this MCP server. Omitted from response bodies when the caller lacks invoke permission on the server.

Show child attributes

auth_type · enum<string>

Authentication scheme used by the MCP server.

Available options: headers, oauth

oauth_provider_id · string<uuid> | null

OAuth provider ID for legacy shared OAuth providers, when configured.

oauth_mode · enum<string>

OAuth mode used by an OAuth MCP server.

Available options: legacy_shared_provider, per_user_dynamic_client

created_at · string<date-time>

updated_at · string<date-time>

mcp_vendor_id · string | null

vendor_id · string | null

external_system_id · string | null

can_invoke · boolean

Whether the caller has invoke permission on this server. Omitted when ambient permissions already imply invoke.