How MCP Tools Work in StackJack

StackJack exposes your MSP stack to AI assistants as MCP tools. This page explains what a tool is, how tools are named, what a tool call returns, and why tools sometimes appear or disappear from your AI assistant's tool list.

What is an MCP tool?

MCP (Model Context Protocol) is an open standard that lets AI applications — Claude, Microsoft Copilot, Cursor, VS Code, and others — call external capabilities in a structured way. Each capability is a tool: a named operation with typed parameters and a description the AI can read.

When you connect an AI assistant (we call it a harness — the app hosting the AI) to your StackJack MCP endpoint, the harness downloads the list of tools available to it. From then on, the AI can call those tools on your behalf: look up a ticket in your PSA, list devices in your RMM, create a quote, and so on.

StackJack serves a large and growing connector catalog, plus a set of StackJack platform tools that work without any connector. A broadly authorized connection can still receive a very large list, but StackJack filters it for your tenant's subscriptions, plans, client grants, enabled product features, and configured catalog mode (see Why tools appear and disappear below).

Tool naming: connector prefixes

Every connector tool follows the pattern <prefix>_<action>. The prefix tells you (and the AI) which product the tool talks to:

Examples: halo_list_tickets, cw_get_company, ninja_list_devices, stackjack_session_info.

Two naming details worth knowing:

• Liongard version suffixes. Liongard tools that call the vendor's older v1 API carry a _v1 suffix (for example liongard_list_systems_v1) to distinguish them from the v2 surface.
• StackJack platform tools (stackjack_*) are not tied to any connector — they report on your session, platform status, support tickets, and automations. See StackJack platform tools.

What a tool call returns

For normal JSON APIs, StackJack's default is raw JSON passthrough: the vendor's response fields and envelope reach the harness without being mapped into a smaller StackJack-specific model. StackJack does not summarize or reinterpret the business data. File downloads, non-JSON vendor protocols, and opt-in response shaping need an MCP-compatible representation, so do not assume that every tool is byte-for-byte passthrough; each generated tool description states its actual return contract.

Why this matters to you:

• Fidelity when passthrough applies. For a normal JSON response that is not shaped, the AI sees the vendor's fields and envelope rather than a reduced StackJack model.
• Vendor documentation applies. If you want to understand a response field, the vendor's own API documentation describes it.
• Pagination and filters are the vendor's. Each connector keeps its native pagination style and page-size limits, because the response envelope is the vendor's.

When StackJack adapts a response

The common adaptations are:

• Files and exports. Most tools that download a PDF, spreadsheet, CSV, image, or quarantine object store it temporarily and return a JSON envelope with a short-lived, read-only download URL. Examples include Action1 exports, ImmyBot spreadsheets, Liongard v1 reports, ESET quarantine downloads, ScalePad exports, and UniFi Protect snapshots. The generated tool description gives the URL lifetime. A few tools use a different documented representation: pax8_download_all_quote_attachments, for example, returns the ZIP as a base64 field in JSON. If the vendor already returns a signed URL or base64 inside its own JSON, StackJack normally leaves that vendor response intact.
• Non-JSON vendor protocols. A connector whose upstream API returns XML can structurally normalize that response to JSON so an MCP client can consume it. The TD SYNNEX legacy XML tool family is one example. The tool catalog calls out these cases.
• Response shaping. Response-shaping rules ship disabled. When you enable a preset or custom rule, StackJack can remove a curated low-value metadata block (such as a static filter catalog) before the response reaches your AI. It does not rename or reinterpret the surviving data, and error bodies are not eligible. See Response shaping.

The connection argument

If your organization holds more than one connection of a connector — one Jamf Pro server per customer, say — every tool of that connector carries an extra optional argument named connection. See Several connections of one connector.

• It appears only when there is a choice to make. A connector with one connection serves its tools exactly as it always did, and the argument is not offered.
• It takes a connection's name or its key, case-insensitively. The tool's own description lists the names, so your AI can read them without asking. Above twelve connections the description points at stackjack_list_connections instead of listing them all.
• Omit it for the default connection. That is what every call did before you added a second one.
• A pinned endpoint refuses it. If an admin pinned that client to one connection, naming any other connection is refused with an explanation rather than quietly served from the wrong customer, and the refusal names only the connection the endpoint is pinned to.
• stackjack_list_connections lists them. It reports every connection of every connector, which one is the default, which one this endpoint is pinned to, and whether each is enabled and healthy. It contains no secrets.
• The response says which one served the call. StackJack adds the serving connection's name to the result's protocol metadata, beside the tool's own answer rather than inside it, whenever the connector has more than one connection. The vendor's JSON is untouched.

Safety hints: read-only and destructive flags

Every tool carries machine-readable safety hints defined by the MCP standard. Read-only means the operation is classified as fetching data without changing it. Destructive is a separate, higher-risk hint used for operations that delete data or can have an irreversible or unusually consequential effect. A write can therefore be non-read-only without being marked destructive; the absence of a destructive hint never means the tool is read-only. Compatible harnesses can use these hints when deciding whether to ask for confirmation, but confirmation behavior belongs to the harness and is not guaranteed by StackJack.

Read-only is not the same as harmless. A read can return passwords, personal data, or a customer's full ticket history to whatever AI application asked for it, so scope a client's tool selection to the data you are willing to expose, not only to the changes you are willing to allow.

Destructive tools and confirmation

Connector guides describe some actions as destructive. That label is a classification StackJack publishes, not a promise that somebody will be asked before the action runs.

StackJack marks this action as destructive. Whether your AI application asks for confirmation depends on its settings. Review those settings and restrict available tools before enabling destructive actions.

Five different things get called "confirmation" in conversation. StackJack enforces three of them. The one that decides whether you see a prompt before a tool runs is not one of StackJack's:

Vendor consent is a sixth, separate thing. When you authorize a connector by signing in, the vendor's own consent screen decides what StackJack's calls may do inside that product. It is granted once at setup and is never re-shown per tool call.

What this means before you enable destructive tools:

1. Decide which destructive tools a connection genuinely needs, and select only those — see Choosing tools for each client. A tool that is not in the selection cannot be called at all, which is stronger than any prompt.
2. Check the approval settings in the AI application itself, and test one destructive call to see whether it actually asks.
3. For unattended work, use an Automation and keep it in dry run until you have read the recorded attempts.

Ordinary writes are not destructive. Creating a ticket, updating a field, or adding a note is a write with no destructive hint, and treating every write as destructive makes the label useless where it matters.

Why tools appear and disappear from your harness

The tool list your harness sees reflects discovery-time authorization and presentation rules. A connector tool is listed only when all of these are true:

1. Your tenant has an active subscription for that tool's connector.
2. The tool's required plan tier is within your connector subscription's plan (see Plan tiers and tool gating).
3. If your MCP client or team member account has a restricted tool selection, the tool is in that selection (see Choosing tools for each client).
4. For an interactive MCP connection, the connector has been configured at least once. A subscribed connector that was never set up is not listed. A connector that was set up still counts as configured when it is disabled, invalid, or temporarily unhealthy, so a health failure does not make the connector family disappear mid-session. Automations are excluded from this presentation-only rule because their run-specific client already carries an explicit tool policy.

So if a tool "disappeared," the usual causes are: a plan downgrade, a canceled connector subscription, an admin narrowing the client's selection, a never-configured connector, or a feature/catalog-mode change. Discovery authorization does not promise that every listed call will succeed: StackJack deliberately advertises writes to a dry-run Automation so it can record the attempted action and then block execution, and credentials, billing state, monthly allowance, consent, ordered-chain, fixture, and vendor checks can still refuse a call at runtime. See Tool errors and troubleshooting.

There is also a cause that has nothing to do with StackJack's filtering: some AI clients cap or silently truncate large tool lists. If a harness seems to be missing tools even though StackJack is serving them, a client-side budget may be the reason. StackJack's catalog modes (compact and minimal) solve this by serving a small, searchable tool surface instead of the full list while permitted, configured tools remain reachable on demand. Organizations can turn catalog modes explicitly on or off on the Settings page; before either choice is saved, StackJack may reduce a known capped harness per connection when its usable catalog exceeds the configured operational threshold. See Choosing tools for each client and managing harness tool limits.

Tip: many harnesses cache the tool list. StackJack cannot push a live update into an open session, so stackjack_refresh_tool_list reports the current catalog version and tells the harness to re-list tools. If the harness still shows a stale list, disconnect and reconnect its StackJack MCP server.

Guidance notes on tool descriptions

StackJack operators can publish per-tool guidance — for example, "this tool is deprecated, use the v2 tool instead." Published guidance is appended directly to the tool's description, so your AI reads it automatically during discovery. You can also ask the AI to call stackjack_get_tool_guidance for a specific tool.

Where to find each connector's tool list

Per-connector reference pages publish every tool's name, generated description, human-readable parameter table, required plan, and access classification — see Connector tool catalogs. When a harness needs the machine-readable JSON input schema, use stackjack_get_tool_catalog with schemas included or stackjack_describe_tools while catalog mode is active. You can also open a connector's API Permissions planner from Connectors (the /permissions route remains a direct-link alternative; see the guide), or ask your connected AI to call stackjack_list_tools. That diagnostic tool projects connector families whose credentials loaded for its current request; if a subscribed family is unexpectedly absent, run stackjack_health_check because the protocol's own tool discovery deliberately keeps a configured family visible across a transient credential-load failure.