---
title: "List tools"
method: GET
path: "/client/mcp/tools"
tags: ["Tool gateway"]
---

# List tools

`GET /client/mcp/tools`

## Request

- Base URL: `https://api.roar-ai.com`
- URL: `https://api.roar-ai.com/client/mcp/tools`
- Auth: HTTP bearer

Every tool your servers list, with its state. Only `served` tools reach an agent. Requires `mcp:read`.

## Query parameters

- `upstreamId` string, uuid

## Response `200`

Tools

- McpToolList
  - `data` McpTool[], required
    - `id` string, uuid, required
    - `clientId` string, uuid, required
    - `upstreamId` string, uuid, required
    - `name` string, required: The server’s own name for the tool
    - `definition` object, required: The tool exactly as the server lists it (description, inputSchema, annotations …) — what an agent’s model reads
      - `name` string, required
    - `definitionHash` string, required: Fingerprint of the definition as listed now. Approving sends it back
    - `approvedHash` string, nullable, required: The fingerprint that was approved; null if never
    - `status` 'active' | 'disabled', required
    - `removedAt` string, date-time, nullable, required: Set when the server stops listing it
    - `effectOverride` 'reads' | 'changes', nullable, required: Your word on what the tool does; null to go by the server’s own `readOnlyHint`
    - `effect` 'reads' | 'changes', required: What the gateway treats it as: your override, else `reads` only when the server marks it read-only. Decides what “ask before changes” asks about
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required
    - `namespacedName` string, required: What agents call it: `<server>__<tool>`
    - `state` 'served' | 'removed' | 'disabled' | 'unapproved' | 'drifted' | 'lock_mismatch' | 'bad_name', required: Only `served` reaches an agent. `drifted`: approved, then changed by the server. `lock_mismatch`: a locked input no longer fits the tool
    - `fixedArgs` object, nullable, required: Locked inputs, `{ name: value }`: the gateway always sends these values, and agents never see these inputs. Null for none
    - `descriptionOverride` string, nullable, required: What agents read instead of the server’s description; null for the server’s own
    - `lockIssues` object[], required: Locks that no longer fit the tool as its server lists it today
      - `name` string, required
      - `problem` string, required

## Other responses

- `404`: No such tool server

---

[API](https://skmtc.dev/roar-ai/apis/roar-ai-api.md) · [All operations](https://skmtc.dev/roar-ai/apis/roar-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/roar-ai/apis/roar-ai-api/revisions/37e4d0d5a7fe?raw)