Skip to content

List a server's tool grants

GET
/admin/ai/mcp-clients/{id}/tools

Returns the tool grants saved for this server, on or off, each with its capability and cost estimate. It’s the saved list; the server isn’t asked.

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 gets a plain-text 400, even when you aren’t signed in. Otherwise signed-out callers get 401 and callers without the permission 403.

The list is sorted by tool name. It can come from a copy kept in memory, which can be out of date after a grant change or a server delete; read from the database, an id that matches no server gets an empty list, not 404. Server errors get a plain-text 500.

id
required
string format: uuid

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

The server’s tool grants, sorted by tool name; empty when there are none.

Array<object>

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