Skip to content

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.

id
required
string format: uuid

The registration’s ID. A value that isn’t a UUID gets a plain-text 400.

tool
required
string
>= 1 characters <= 128 characters

The tool name, matched exactly after percent-decoding. Its length isn’t checked; a path without one doesn’t match this operation.

The grant to save. Every field replaces the saved one.

object
additional_capability

Leave it out, or send an empty string, for none; this removes a capability saved before.

string
cost_estimate_micros
required

A missing value is saved as 0; a negative one gets a plain-text 500.

integer format: int64
enabled
required

A missing value is saved as false.

boolean

The grant as saved.

One tool this server may be called with. Calls naming any other tool are refused.

object
server_id
required

The registration this grant belongs to.

string format: uuid
tool_name
required

The tool’s name, matched exactly, case included, when a call names a tool.

string
>= 1 characters <= 128 characters
additional_capability

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.

string
nullable
cost_estimate_micros
required

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.

integer format: int64
enabled
required

Whether the tool can be called. A disabled grant refuses calls like a missing one.

boolean

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Resource not found

object
error
required

Human-readable error summary

string
Example
the request could not be completed