Skip to content

Remove a tool grant

DELETE
/admin/ai/mcp-clients/{id}/tools/{tool}

Removes the saved grant for the tool on this server. It answers 204 even when there’s no such grant or server.

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 or a tool name that can’t be percent-decoded 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.

The tool name is matched exactly after percent-decoding, and the declared 404 isn’t used. Calls can still see the removed grant for a while, since a copy kept in memory may be out of date, and a call that has already passed the grant check isn’t stopped. Removing isn’t recorded in the audit log. 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.

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.

Removed, or there was nothing to remove.

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