Add or replace a tool grant
PUT /admin/ai/mcp-clients/{id}/tools/{tool}
Saves the named tool’s grant on this server, adding or replacing it, and returns it. The tool isn’t checked against the server’s tools.
You need mcp.client.admin or system.admin for the whole install;
a permission held only for a team doesn’t count, and neither does
ai.admin. An id that isn’t a UUID, a tool name that can’t be
percent-decoded, or a body that can’t be decoded into the request
shape gets a plain-text 400, even when you aren’t signed in.
Otherwise signed-out callers get 401 and callers without the
permission 403. A path with no tool name doesn’t match this
operation and gets a 404 before reaching it.
Every field is replaced: a missing enabled is saved as false, a
missing cost_estimate_micros as 0, and a missing or empty
additional_capability removes any extra capability. The tool name
is used after percent-decoding and matched exactly, case included;
its length isn’t checked. An unknown server id or a negative cost
gets a plain-text 500, so the declared 404 isn’t used.
A saved grant doesn’t by itself allow calls: the server and the
grant must be on, calling the tool needs mcp.client.use and, if
the grant names one, additional_capability, and the privacy and
spending checks still apply. Managing grants doesn’t need either
capability. A call can still see the previous grant for a while,
since a copy kept in memory may be out of date. Saving isn’t
recorded in the audit log.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The registration’s ID. A value that isn’t a UUID gets a plain-text 400.
The tool name, matched exactly after percent-decoding. Its length isn’t checked; a path without one doesn’t match this operation.
Request Body required
Section titled “Request Body required ”The grant to save. Every field replaces the saved one.
object
Leave it out, or send an empty string, for none; this removes a capability saved before.
A missing value is saved as 0; a negative one gets a plain-text 500.
A missing value is saved as false.
Responses
Section titled “ Responses ”The grant as saved.
One tool this server may be called with. Calls naming any other tool are refused.
object
The registration this grant belongs to.
The tool’s name, matched exactly, case included, when a call names a tool.
A capability needed, besides mcp.client.use, to call this tool. Left out when there’s none. It isn’t checked to be a real capability.
Your estimate of one call’s cost, in millionths of a dollar. Before each call it’s added to the recorded spending and compared with the spending limit, without being reserved, and the usage record of a call that reaches the server carries it when that record is written; it isn’t a price.
Whether the tool can be called. A disabled grant refuses calls like a missing one.
Authentication required, missing, or invalid
object
Human-readable error summary
Example
the request could not be completedExample
{ "error": "authentication required: sign in and retry with a valid session or API token"}Authenticated but missing required capabilities
object
Human-readable error summary
Example
the request could not be completedResource not found
object
Human-readable error summary
Example
the request could not be completed