# MCP tools reference

Source: https://imqueue.org/mcp/tools/
Published: 2026-07-22
Updated: 2026-08-03
Author: @imqueue maintainers (https://github.com/imqueue)

Every tool the @imqueue MCP server exposes — what it does, what it takes, what comes back, and an example prompt that triggers it.

The server exposes its tools in three groups. **Documentation** and **scaffolding**
tools work everywhere with no dependencies. The **CLI bridge** tools require
[`@imqueue/cli`](https://imqueue.org/cli/) (`imq`) on your `PATH` — call `cli_status` first, and if
it is missing either `cli_install` it or fall back to the offline `scaffold_*`
tools.

Which of them you get depends on how you connect. The **local** install has all
thirteen. The **hosted** endpoint has six, all read-only: the documentation and
scaffolding tools plus `local_install_guide`. The CLI-bridge tools act on your own
machine — your files, your processes, your CLI config — which a server on
Cloudflare's edge cannot reach, so it does not offer them at all. They are not in
its tool list.

You never call these by hand — your agent picks them based on their descriptions.
This page is so you know what it *can* do, and what is safe.

## Documentation

### `search_docs`
Search the official @imqueue docs (guides, tutorial, CLI manual, API reference,
articles) and return the most relevant pages with their URLs.

- **Input:** `query` (string) — what you want to find; `limit` (1–20, default 6).
- **Returns:** a ranked list of matching pages with titles, sections and URLs.
- **Side effects:** none (read-only; fetches imqueue.org).
- **Example prompt:** *"How do I expose a method on an @imqueue service?"*

### `get_doc`
Fetch the full markdown of a documentation page by its URL (as returned by
`search_docs`), ready to read and quote.

- **Input:** `url` (string) — an `imqueue.org` page URL.
- **Returns:** the page as plain markdown.
- **Side effects:** none. **Host-locked to `imqueue.org`** — it will not fetch any other host.
- **Example prompt:** *"Read the getting-started guide and summarise the steps."*

### `list_packages`
The main @imqueue packages with a one-line summary and install command, so the
agent picks the right one before writing code.

- **Input:** none.
- **Returns:** the package catalog (e.g. `@imqueue/rpc`, `@imqueue/core`, `@imqueue/cli`) with install commands.
- **Side effects:** none.
- **Example prompt:** *"Which @imqueue package do I need for delayed jobs?"*

## Scaffolding (offline)

### `scaffold_service`
Generate an idiomatic `@imqueue/rpc` service — an `IMQService` subclass with
`@expose()`d, JSDoc-typed methods plus a bootstrap that starts it.

- **Input:** `name` (string); `methods` (optional array of `{ name, description?, params?, returns? }`).
- **Returns:** ready-to-save TypeScript. Omitting `methods` yields a starter template.
- **Side effects:** none — returns code as text; writes nothing.
- **Example prompt:** *"Scaffold an @imqueue user service with getUser and createUser."*

### `scaffold_client`
@imqueue generates the **real** typed client from a **running** service, so types
never drift. This tool returns the exact command to do that plus an illustrative
usage snippet — it does not fabricate a client that could go stale.

- **Input:** `service` (string); `methods` (optional, to shape the example).
- **Returns:** the `imq client generate` command and an example call.
- **Side effects:** none.
- **Example prompt:** *"How do I get a typed client for my user service?"*

## CLI bridge tools

The CLI bridge tools drive the real `imq` binary. Every call runs with **stdin
closed and a timeout**, so a command that would prompt interactively fails fast with guidance
rather than hanging your agent.

### `cli_status`
Detect whether `imq` (@imqueue/cli) is installed and report its version. The agent
should call this before any other CLI-bridge tool.

- **Input:** none. **Read-only.**
- **Example prompt:** *"Is the @imqueue CLI installed?"*

### `cli_install`
Install `@imqueue/cli` globally via `npm install -g @imqueue/cli` when it is
missing.

- **Input:** `version` (optional npm version/tag, default `latest`).
- **Side effects:** installs a global npm package (may need a writable prefix or elevated permissions).
- **Example prompt:** *"Install the @imqueue CLI for me."*

### `cli_help`
Run `imq [command] --help` and return the exact, version-accurate flags — the
agent uses this to build a non-interactive `create_service` call.

- **Input:** `command` (optional, e.g. `"service create"`). **Read-only.**
- **Example prompt:** *"What flags does imq service create take?"*

### `create_service`
Scaffold a real, provider-wired service via `imq service create`.

- **Input:** `name`; `path?`; `flags?` (from `cli_help`); `cwd?`; **`apply?`**.
- **Safety:** runs as a **dry-run by default** (shows the plan, writes nothing). A real run requires **`apply: true`** — it can write files, init git, configure CI and push to a remote, so an agent should only apply with your clear intent.
- **Example prompt:** *"Create a payments service — show me the plan first."*

### `generate_client`
Run `imq client generate <Service>` to emit the real, fully-typed client.

- **Input:** `service`; `path?`; `cwd?`.
- **Requirement:** the target service must be **running** — the CLI introspects the live service.
- **Example prompt:** *"Generate the typed client for the running UserService."*

### `fleet`
Run `imq ctl <action>` over a directory of service repositories.

- **Input:** `action` (`start` | `stop` | `restart` | `status`); `path?`; `services?`; `update?`; `calm?`; `verbose?`; `cwd?`.
- **Safety:** `status` is read-only; `start` / `stop` / `restart` change running processes.
- **Example prompt:** *"Start my local fleet and tell me what's running."*

### `config`
Run `imq config <action>` to manage CLI configuration.

- **Input:** `action` (`check` | `get` | `set` | `init`); `option?` (dot-path for nested keys); `value?`; `cwd?`.
- **Safety:** `check` / `get` are read-only; `set` writes one value; `init` is interactive, so automation should prefer `set`.
- **Example prompt:** *"Set my default CI provider to github-actions."*

### `logs`
Work with logs of services started by `imq ctl`.

- **Input:** `action` (`dump` (default) | `clean`); `services?`; `prefix?`; `cwd?`.
- **Safety:** `dump` reads the current combined logs and exits — it **never follows/streams**, and output is capped so it can't flood the agent; `clean` deletes collected logs.
- **Example prompt:** *"Show me the recent logs for the auth service."*

## Hosted endpoint only

### `local_install_guide`
Registered **only on the hosted server** ([`mcp.imqueue.org`](https://imqueue.org/mcp/#hosted-endpoint)),
where it is how an agent discovers that the CLI-bridge tools need a local install.
The local server does not expose it — there is nothing left to install.

- **Input:** none.
- **Returns:** the exact steps to install the full MCP server on your machine.
- **Side effects:** none — it returns instructions, it does not install anything.
  That is also why it is named `local_install_guide` rather than `install_locally`,
  as it was before 3.0.0: a tool's name has to describe what it actually does.
- **Example prompt:** *"Why can't you start my fleet?"*

The CLI-bridge tools above are **absent** from the hosted server's tool list — it
does not list them and cannot run them. Until 3.0.0 it listed them and answered
with install guidance instead, which was worse: an agent that picked `fleet` got
prose rather than a fleet. See [Safety & troubleshooting](https://imqueue.org/mcp/security/).

## Read-only vs state-changing `@imqueue` MCP tools

A quick map of which `@imqueue` MCP tools are safe to let an agent call freely,
and which change your machine:

| Read-only | Changes state |
|---|---|
| `search_docs`, `get_doc`, `list_packages` | `cli_install` (global npm install) |
| `scaffold_service`, `scaffold_client` | `create_service` **with `apply: true`** |
| `cli_status`, `cli_help` | `generate_client` (writes client files) |
| `create_service` (default dry-run) | `fleet start/stop/restart` |
| `config check/get`, `fleet status` | `config set`, `logs clean` |
| `logs dump` | |

Every tool declares this in machine-readable form too. Each one carries the MCP
`readOnlyHint`, `destructiveHint` and `openWorldHint` annotations, so a client can
decide what to run without asking you rather than guessing from the name. Tools that
accept a mix of operations own their **worst** case: `fleet` is marked destructive
because `stop` is, even though `status` is not. Every tool on the hosted endpoint is
`readOnlyHint: true`.

See [Safety & troubleshooting](https://imqueue.org/mcp/security/) for the full trust model, and
[Agent workflows](https://imqueue.org/mcp/workflows/) for how these tools chain together in practice.