**mcptool is under heavy development and not yet ready for use - check back later!** # mcptool A versatile command‑line utility for connecting to, testing, and probing **MCP** servers from your terminal. **mcptool** aims to provide a unified Swiss‑army‑knife for developers, administrators, and CI pipelines that interact with servers speaking the **MCP** protocol. --- ## Key Features * **One‑liner connections** – quickly open an interactive MCP session without extra setup. * **Health & latency checks** – measure round‑trip times with a simple `mcptool mcp ping`. * **Capability discovery** – automatically probe which optional commands a server supports. * **Script‑friendly output** – machine‑readable JSON and quiet modes for automation. ## Quick Start ```bash cargo install mcptool ``` ## Usage After installation the binary is available as `mcptool`. Use `--help` on any sub‑command for detailed flags. ### Target Specification Every sub‑command that expects a *target* accepts a TCP endpoint, HTTP/HTTPS endpoint, a local command to be spawned in **stdio** mode, or a stored authentication entry. | Variant | Syntax | What Happens | | ---------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------- | | **Implicit TCP** *(default)* | `host[:port]` | Connects via TCP. If no port is given, the command‑specific default applies. | | **Explicit TCP** | `tcp://host[:port]` | Same as above but unambiguous when the host could contain a scheme prefix. | | **HTTP** | `http://host[:port]` | Connects via HTTP. If no port is given, defaults to port 80. | | **HTTPS** | `https://host[:port]` | Connects via HTTPS. If no port is given, defaults to port 443. | | **Stdio Command** | `cmd:// [args…]` | Spawns the program locally and speaks MCP over its STDIN/STDOUT pipes. Use quotes when the command contains spaces. | | **Authentication** | `auth://` | Uses a stored authentication entry (see Authentication section below). | > **Example targets** > > * `api.acme.ai` (TCP, default port) > * `tcp://api.acme.ai:7780` (TCP, port 7780) > * `http://api.acme.ai` (HTTP, port 80) > * `https://api.acme.ai:8443` (HTTPS, port 8443) > * `"cmd://./my‑stdio‑server --some --argument"` (local process) > * `auth://github` (stored authentication entry) ### Global Commands (run from your shell) | Command | Purpose | | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `mcptool connect [--script ]` | Connect to the target. Without **`--script`** you drop into an interactive prompt (`>`). With **`--script`** mcptool reads one sub‑command per line from *file*, executes them sequentially, prints results, and exits. | | `mcptool proxy --log-file ` | Transparently open a stdio transport, and proxy all traffic to target, recording it to *file*. | | `mcptool testserver [--stdio] [--tcp] [--port ]` | Run a test MCP server with verbose logging. Use `--stdio` for stdio transport, `--tcp` for TCP transport, or default HTTP on specified port. | | `mcptool version` | Display the mcptool build version & linked MCP revision. | | `mcptool help [sub-command]` | Show contextual help for any command. | ### Global Options | Option | Purpose | | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--json` | Output results in JSON format | | `--logs ` | Enable logging with specified level (debug, info, notice, warning, error, critical, alert, emergency) | | `--color` | Force color output | | `--no-color` | Disable color output | | `--quiet` | Suppress all output including JSON output | ### MCP Commands (usable inside the prompt *or* from the shell with a ``) When you are **inside the prompt**, type these commands **without** the `mcptool` prefix and without a target. From the regular shell, prefix them with `mcptool mcp` and provide a ``. | Prompt form | Shell form | Purpose | | --------------------------------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `ping` | `mcptool mcp ping ` | Measure round‑trip latency. | | `init` | `mcptool mcp init ` | Initialize connection and display server information. | | `listtools` | `mcptool mcp listtools ` | List all MCP tools (`tools/list`). | | `listprompts` | `mcptool mcp listprompts ` | List predefined prompt templates (`prompts/list`). | | `listresources` | `mcptool mcp listresources ` | List server resources such as databases or file trees (`resources/list`). | | `listresourcetemplates` | `mcptool mcp listresourcetemplates ` | List resource templates available for instantiation. | | `setlevel ` | `mcptool mcp setlevel ` | Set the logging level on the MCP server. | | `calltool [options]` | `mcptool mcp calltool [options]` | Invoke a tool with arguments. Options: `--arg key=value`, `--interactive`, `--json` | | `readresource ` | `mcptool mcp readresource ` | Read a resource by URI. | | `getprompt [--arg key=value]` | `mcptool mcp getprompt [--arg key=value]` | Get a prompt by name with optional arguments. | | `subscriberesource ` | `mcptool mcp subscriberesource ` | Subscribe to resource update notifications. | | `unsubscriberesource ` | `mcptool mcp unsubscriberesource ` | Unsubscribe from resource update notifications. | | `complete ` | `mcptool mcp complete ` | Get completion suggestions for prompt or resource arguments. | ### Interactive Prompt & Script Mode Once connected **without `--script`**, you can run any sub‑command without specifying the target again, just as you would on the normal command line. If you **provide `--script mysession.mcp`**, the file is read line‑by‑line and each line is dispatched exactly as if you had typed it at the prompt. After the last line executes the connection closes automatically. ```text $ mcptool connect api.acme.ai Connected to api.acme.ai (tcp, proto‑rev 9) > ping 107 ms > listtools summarize translate moderate > calltool summarize --arg text="Hello world" {"summary":"Hello 🌍"} > exit ``` ### Authentication Mcptool supports OAuth authentication for HTTP/HTTPS endpoints. Authentication entries can be managed using the `mcptool auth` commands: | Command | Purpose | | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `mcptool auth add [options]` | Add a new OAuth authentication entry with interactive setup | | `mcptool auth list` | List all stored authentication entries | | `mcptool auth remove ` | Remove an authentication entry | | `mcptool auth renew ` | Renew the access token using the refresh token | Once an authentication entry is stored, you can use it with any MCP command by using the `auth://` target syntax: ```bash # Add GitHub authentication mcptool auth add github # Use the stored authentication mcptool mcp ping auth://github mcptool mcp listtools auth://github mcptool connect auth://github ``` ### Examples ```bash # Check latency to a remote MCP server (implicit TCP) mcptool mcp ping api.acme.ai # Check latency to a local stdio server mcptool mcp ping "cmd://./my‑stdio‑server --some --argument" # Use stored authentication (e.g., for GitHub Copilot) mcptool mcp ping auth://github # List tools using authentication mcptool mcp listtools auth://github # Connect via TCP on a non‑default port and immediately run a status query, then exit mcptool calltool tcp://dev.acme.ai:7780 -- status # Execute a tool with arguments on a local stdio endpoint mcptool mcp calltool "cmd://./my‑stdio‑server --some --argument" summarize --arg text="Hello world" # Use interactive mode to be prompted for each parameter mcptool mcp calltool api.acme.ai chat.complete --interactive # Pass a complex JSON payload via STDIN echo '{"text": "Hello world", "model": "gpt-4"}' | mcptool mcp calltool api.acme.ai chat.complete --json # Run a scripted sequence without entering the prompt mcptool connect api.acme.ai --script mysession.mcp ```