---
title: "The callTool language | Mesher docs: MCP connectors for AI agents"
url: https://mesher.sh/docs/calltool
description: "Reference for callTool, the single MCP tool Mesher exposes: every command, the -b, -q and -h flags, profiles, parsing rules and the CLI-only extras."
---

# The callTool language

One MCP tool, a command line for every connector: commands, flags and rules.

`callTool` takes `{"command": "…", "body"?: {…}, "query"?: {…}, "headers"?: {…}, "profile"?: "…", "format"?: "json"|"toon"}`. Start with `help`:

```text title="callTool"
help
connectors
searchTools 'send email', 5
gmail.help
gmail.tools
gmail.tools sendEmail help
gmail.tools sendEmail -b '{"to":"ada@example.com","subject":"Hi"}'
gmail.tools listMessages -q maxResults=10 -q labelIds=INBOX,UNREAD
gmail.tools auth status
gmail@work.tools listMessages -q maxResults=10
gmail.resources read gmail://labels
gmail.prompts get summarize -b '{"thread":"t-1"}'
```

## Commands

| Command | What it does |
|---|---|
| `help` | Overview and the installed connectors |
| `connectors` | List the installed connectors |
| `searchTools <query> [,] [<limit>]` | Search the tools of every connector |
| `resources` / `prompts` | List the resources or prompts of every connector |
| `<c>` or `<c>.help` | Connector overview: title, auth status, tool count |
| `<c>.searchTools <query> [,] [<limit>]` | Search one connector's tools, best first |
| `<c>.tools` | List the tools |
| `<c>.tools <tool> help` | Tool help, generated from its schemas |
| `<c>.tools <tool> [-b JSON] [-q …]… [-h …]…` | Call a tool |
| `<c>.tools auth [login\|status\|logout]` | Sign in (the default), inspect, or forget the credential |
| `<c>.resources [read <uri>]` | List the resources, or read one |
| `<c>.prompts [get <name> [-b JSON]]` | List the prompts, or get one |
| `<c>@<profile>.…` | Any connector command, with the credential of that profile |

## Rules

- Words are split like a POSIX shell: single quotes, double quotes and backslash escapes work.
- A comma followed by a space or the end of the line separates two positional arguments, so `'xyz', 10` and `xyz 10` are the same. Any other comma is part of its word (`-q ids=1,2`).
- `-b` (`--body`) is the JSON body. It may appear once and is checked against the tool's `inputSchema`.
- `-q` (`--query`) takes `k=v` or a JSON object, and `-h` (`--header`) takes `k:v` or a JSON object. Both repeat and merge; later values win.
- **`-h` means header, not help.** Help is the word `help` or `--help`, and it wins over everything else on the line.
- The structured `body` field replaces `-b`; `query` and `headers` merge over `-q` and `-h`; `profile` replaces the command's `@<profile>`.
- The search limit defaults to 10. Outside 1–100 it is an error, not clamped.
- Bad arguments and parse errors come back as tool errors (`isError: true`), so the model can read what to fix.

## On the CLI

The dot becomes a space, `-b @file` and `-b -` (stdin) work, and `call` takes a line exactly as `callTool` does:

```sh
$ mesher gmail tools sendEmail -b @mail.json
$ mesher gmail searchTools unread, 10
$ mesher call 'gmail.tools sendEmail help'
$ mesher gmail tools listMessages --profile work
```

Only the CLI can read and write files: `-f <property>=<path>` sets a body property from a file (base64-encoded when the schema says so), and `-o <path>` saves the files a result carries. `callTool` refuses both, because a server must not touch its own files for an MCP client.

```sh
$ mesher gmail tools sendEmail -b @mail.json -f attachment.data=./report.pdf
$ mesher drive resources read drive://files/report -o ./downloads/
```

## Signing in to a service

`<c>.tools auth` collects whatever the connector's manifest asks for. On the CLI, API keys are read from the terminal or stdin and OAuth opens a browser. Over MCP the server answers with a link to its `/connect/<c>` page, as a URL elicitation where the client supports it.

### Store the OAuth client first

An OAuth connector needs your OAuth app (its client id, and a secret if the provider wants one) before anyone can sign in. Store it once per connector. The part before `=` names the connector, the rest is the client id, and the flag repeats for more connectors:

```sh
# --oauth-client <connector>=<client id>[:<secret>]
$ export MESHER_GMAIL_CLIENT_SECRET=…   # keeps the secret out of `ps`
$ mesher init --oauth-client gmail=1234.apps.googleusercontent.com
```

- **The secret** can follow the id after a `:`, but an environment variable keeps it out of your shell history and `ps`.
- **Variable names** come from the connector name in capitals, with `-` turned into `_`: `MESHER_<NAME>_CLIENT_ID` and `MESHER_<NAME>_CLIENT_SECRET`.
- **Other places**: `mesher serve` takes `--oauth-client` too, `config.toml` takes an `[oauth.gmail]` table with `client_id` and `client_secret`, and the web UI stores it under the connector's **Configuration › Setup**. A flag wins over a variable, and a variable over the file.
- **Over MCP**, the `manage` connector stores it: `manage.tools setInputs -b '{"connector":"gmail","values":{"client_id":"…"}}'`.

### Then sign in, once per profile

The OAuth app is shared by every profile; only the sign-in is per profile. Each `tools auth` opens your browser, and the CLI catches the answer on a one-shot loopback callback:

```sh
$ mesher gmail tools auth --profile work
$ mesher gmail tools auth --profile personal
$ mesher gmail tools auth status --profile work
```

Over MCP, the same sign-in is `gmail@work.tools auth`, which answers with a link to the server's `/connect/gmail@work` page. See [Profiles](https://mesher.sh/docs/profiles) for more.

Last updated November 21, 2026 · [This page as Markdown](https://mesher.sh/docs/calltool.md) · [Full reference on GitHub](https://github.com/agentrq/mesher/blob/main/README.md)
