Tool Gateway is in beta.
/v1/managed-tools/servers/<server-id>/mcp.
Send an MCP request
Send each MCP message as a JSON-RPCPOST request to the endpoint. A tool kit and the me kit keep no session between requests, so you do not need to send initialize before you list or call tools. A tool kit accepts one message per request and rejects JSON-RPC batches. A single server’s endpoint passes each request to the server as is, and can answer with text/event-stream. If that server uses sessions, send initialize first, and repeat the MCP-Session-Id header it returns on each request.
Every request sends these headers:
X-Api-Key: A LangSmith API key. The key decides whose credentials the call uses. To call as another user, as an agent, or with a profile, see Act as users and agents.X-Tenant-Id: Your workspace ID.Content-Type:application/json.Accept:application/json, text/event-stream.MCP-Protocol-Version: The MCP protocol version the request uses.
2026-07-28 must also send the protocol version and client capabilities in the request’s _meta. They must also repeat the method and tool name in headers:
Mcp-Method: The JSON-RPCmethod, such astools/list.Mcp-Name: Fortools/call, the tool’s name, matchingparams.name.
2026-07-28 request that is missing either header returns 400 with a JSON-RPC error, code -32020.
Protocol version 2026-07-28 is required to get the connection and approval prompts inside the MCP response. Requests on an earlier version, such as 2025-06-18, omit the extra headers and _meta, and get an HTTP error instead of a prompt.
List tools
result.tools lists each tool under the name agents call, such as linear_list_issues. For how Tool Gateway names tools, see How kit tools are named.
The list includes tools on servers you have not connected yet. See Connect when a call asks.
Call a tool
result.content holds the server’s result, passed through unchanged. Treat it as untrusted input to your agent. If the tool itself fails, result.isError is true and the HTTP status is still 200.
Tool Gateway checks the caller’s credential and policies on every call. A call that cannot run returns one of the responses in the following sections.
Connect when a call asks
A tool kit lists all of its tools, including tools on servers the caller has not connected. A call to one of those tools does not run. Instead, Tool Gateway asks the caller to connect the server. How it asks depends on who the caller is acting as and what the client supports.Check before you call
To see which servers a caller still needs to connect, without calling a tool:- From the tool list: A kit’s
tools/listresult names each missing credential, with its sign-in link, inresult._meta["com.langchain.langsmith/missingCredentials"]. The me kit does not include this list. - From the connections endpoint:
GET /v1/managed-tools/kits/<kit-id>/connectionslists each server the kit uses, withconnectedset for the caller. To start a connection, see Connect accounts.
connect_<server>. Calling the placeholder asks the caller to connect, like any other call.
The missing credentials in a tool list can lag behind a connection made since. A tool call always checks the caller’s current credential.
When the caller is a user
A user can connect their own account, so the call returns a sign-in link:- Clients that support URL elicitation: On protocol
2026-07-28, a client that declares theelicitation.urlcapability gets aninput_requiredresult with one link for each server to connect. The client shows the link to the user. After the user connects, the call continues. - Every other client: The call returns
428. Open eachverification_urlin the body, connect, then send the call again.
428 body differs by endpoint. A tool kit or the me kit returns a credentials array, because one call can need more than one server:
credentials array:
kind is oauth for a server that signs in with OAuth, or secret for a server that expects an API key. The link opens a page where the user signs in or enters the key. For OAuth, it can go straight to the service’s own sign-in page. Only the caller should open it: whoever signs in links their account to the caller.
When the caller is an agent or a profile
An agent or a profile cannot connect its own credentials, because no one is present to sign in. The call returns409 with the same credentials array as a 428, but with no sign-in links. A workspace admin must connect the credential for the agent or the profile, then the agent can retry. See Connect accounts.
Approve a tool call
An approval policy pauses each matching call until the caller approves it. The approval comes from the person using the MCP client, not from a separate reviewer. Use it to confirm a call before it runs, not to route calls to an admin. On protocol2026-07-28, a client that supports form elicitation shows an approval form. The form names the tool, its server, the policies that require approval, and the call’s arguments.
- Accept: The call runs.
- Decline or cancel: The call does not run. The result is a tool error with the text “The user declined this tool call, so it did not run.”
403, and the call does not run. To call the tool, use a client that supports form elicitation, or ask an organization admin to change the policy.
A deny policy blocks the call with 403 and "code": "tool_call_blocked". Tool Gateway returns the same response when it blocks a call as unsafe, so the response does not say which one blocked the call. Match on code, because the detail text can change. Blocked tools still appear in tool lists.
Errors
Most error responses are JSON problem details. Thedetail field says what went wrong, and remedy, when present, says what to do next. Two errors use other bodies: an authentication failure can return {"error": "Unauthorized"}, and a missing or mismatched Mcp-Method or Mcp-Name header returns a JSON-RPC error.
A single server’s endpoint passes other status codes from the MCP server through unchanged. For request, response, and rate limits, see Limits.
See also
Connect these docs to your agent of choice via MCP for real-time answers.

