Search a workspace's MCP tools

GET/v1/mcp-tool-search

Search a workspace's MCP tools.

Finds tools by meaning: the query is embedded and compared with the tools' names and descriptions. Only tools the registry would allow a call to are returned (for example, not switched off, drifted or quarantined), best match first; a tool that has been failing lately ranks lower. Each result carries the tool's recent health. A caller's own narrowing (an MCP key's allowlist) is not applied here.

Requires an organization admin key, or a key of that workspace (any role). Returns 400 when q is empty or longer than 1000 characters. Returns 402 when the organization's plan does not include the MCP Gateway. Returns 503 when tool search is turned off.

Authorization

AuthorizationBearer va_
A platform API key (va_...), created under Settings > API keys. Scoped to an organization or one workspace, with an admin or member role. Used by the management API.

Query parameters

organizationstringrequired
The organization's identifier (slug).
workspace_idstring<uuid>required
The workspace whose tools to search (UUID).
qstringrequired
What the tool should do, in plain language. Up to 1000 characters.
limitinteger<int32>
How many tools to return. Default 10, at most 20.

Responses

200application/json

querystring
The query, as searched (trimmed).
dataobject[]
The tools, best match first; a tool that has been failing ranks lower.
Child attributes
- idstring
  {server slug}/{tool name}: how the tool is named across servers (the format of an MCP key's allowlist).
- namestring
  The tool's name.
- titlestring
  The tool's title, when it has one.
- descriptionstring
  The tool's description.
- server_slugstring
  The MCP server that reaches the tool.
- server_namestring
  That server's name.
- integration_slugstring
  The connector behind the server.
- is_privilegedboolean
  Whether the tool is privileged (refused for a caller that received untrusted content recently).
- requires_approvalboolean
  Whether every call to the tool waits for a person's approval.
- scorenumber<double>
  Similarity to the query, 0 to 1, before health is applied to the ranking.
- healthobject
  How a tool has been doing lately: agents' calls through the gateway in the last window_minutes, in this region.
  Child attributes
  - server_slugstring
    The MCP server the calls went through.
  - toolstring
    The tool's name.
  - statusstring
    HEALTHY; DEGRADED (failing sometimes, or slow); OUTAGE (failing most of the time); or UNKNOWN (too few calls to say).
  - reasonstring
    Why, in a sentence. Absent when HEALTHY or UNKNOWN.
  - callsinteger<int64>
    Calls in the window.
  - failuresinteger<int64>
    Calls that failed or timed out at the gateway or the upstream (FAILED, TIMED_OUT).
  - failure_ratenumber<double>
    failures divided by calls, 0 to 1.
  - tool_errorsinteger<int64>
    Calls that went through but on which the tool reported an error (often bad arguments).
  - p50_msinteger<int64>
    Median latency of completed calls, in milliseconds.
  - p95_msinteger<int64>
    95th-percentile latency of completed calls, in milliseconds.
  - last_failure_atstring<date-time>
    When the last failure happened (ISO 8601).
  - window_minutesinteger<int32>
    The length of the window, in minutes.

Request

curl -X GET "https://api.vectoraxis.ai/v1/mcp-tool-search?organization=string&workspace_id=3f6c1a2e-8b4d-4c1e-9a7f-2d5e6b8c9a01&q=string" \
  -H "Authorization: Bearer $VECTORAXIS_API_KEY"

VectorAxis is built by GK Labs, a member of NVIDIA Inception.