mcp-tool-discovery

MCP Tool Discovery

This server registers over 440 snow_* tools across 80 domains and lists none of them. A fresh tool list holds two meta-tools; everything else is behind tool_search. This guide is about getting from "there is probably a tool for this" to a call that actually runs.

No exact total is quoted here, because there are two of them and they disagree: packages/servicenow-mcp/tools.json is what the docs site publishes, the registry is what the running server can dispatch, and nine published tools are missing from the registry (see "Nine tools you can find in the docs but not on the server").

Cold start: two tools

A fresh tools/list on the stdio transport returns exactly this, no matter how many tools exist:

tool_search
tool_execute

That is deliberate. The server's own note puts the full catalog at roughly 71k tokens of schema against about 2k for the two meta-tools. The index is built with every tool marked deferred, and handlers/list-tools.ts returns only meta-tools plus whatever the current session has enabled.

The HTTP transport (the portal) does the opposite — it registers the catalog as non-deferred, so its tools/list returns everything and nothing needs enabling. You can tell which one you are on from the status in a tool_search result: [AVAILABLE] means the server is not gating on the enabled set at all.

The loop

// 1. Search. Found tools are enabled for this session by default.
tool_search({ query: "update-sets" })

// 2. Read the status on each hit:
//    [AVAILABLE] — callable now, nothing had to be enabled
//    [ENABLED]   — deferred, and enabled for this session. Callable now.
//    [DEFERRED]  — NOT callable. Nothing was enabled; see the next section.

// 3. Execute.
tool_execute({ tool: "snow_ensure_active_update_set", args: { name: "Feature: SLA fix" } })

Pass enable: false when you only want to look — it searches without touching session state.

No session id, no tools

This is the failure that wastes an afternoon. Enablement is stored per (tenant, session). With no session id there is nothing to attach it to, so tool_search enables nothing, every hit stays [DEFERRED], and every call is refused: