mcptools

Table of Contents

• Overview
• Difference Between the MCP Inspector and MCP Tools
• Installation
  • Using Homebrew
  • From Source
• Getting Started
• Features
  • Transport Options
  • Output Formats
  • Commands
  • Interactive Shell
  • Web Interface
  • Project Scaffolding
• Server Aliases
• LLM Apps Config Management
• Server Modes
  • Mock Server Mode
  • Proxy Mode
  • Guard Mode
• Examples
  • Basic Usage
  • Script Integration
  • Debugging
• Contributing
• Roadmap
• License

Overview

MCP Tools provides a versatile CLI for working with Model Context Protocol (MCP) servers. It enables you to:

• Discover and call tools provided by MCP servers
• Access and utilize resources exposed by MCP servers
• Create mock servers for testing client applications
• Proxy MCP requests to shell scripts for easy extensibility
• Create interactive shells for exploring and using MCP servers
• Scaffold new MCP projects with TypeScript support
• Format output in various styles (JSON, pretty-printed, table)
• Guard and restrict access to specific tools and resources
• Support all transport methods (HTTP, stdio)

Installation

Using Homebrew (for macOS)

brew tap f/mcptools
brew install mcp

❕ The binary is installed as mcp but can also be accessed as mcpt to avoid conflicts with other tools that might use the mcp command name.

From Source (for Windows and GNU/Linux)

go install github.com/f/mcptools/cmd/mcptools@latest

❕ The binary will be installed as mcptools when but can be aliased to mcpt for convenience.

Windows 11 Running Example

Getting Started

The simplest way to start using MCP Tools is to connect to an MCP server and list available tools:

# List all available tools from a filesystem server
mcp tools npx -y @modelcontextprotocol/server-filesystem ~

# Call a specific tool
mcp call read_file --params '{"path":"README.md"}' npx -y @modelcontextprotocol/server-filesystem ~

# Open an interactive shell
mcp shell npx -y @modelcontextprotocol/server-filesystem ~

Features

MCP Tools supports a wide range of features for interacting with MCP servers:

Usage:
  mcp [command]

Available Commands:
  version       Print the version information
  tools         List available tools on the MCP server
  resources     List available resources on the MCP server
  prompts       List available prompts on the MCP server
  call          Call a tool, resource, or prompt on the MCP server
  get-prompt    Get a prompt on the MCP server
  read-resource Read a resource on the MCP server
  shell         Start an interactive shell for MCP commands
  web           Start a web interface for MCP commands
  mock          Create a mock MCP server with tools, prompts, and resources
  proxy         Proxy MCP tool requests to shell scripts
  alias         Manage MCP server aliases
  configs       Manage MCP server configurations
  new           Create a new MCP project component
  help          Help about any command
  completion    Generate the autocompletion script for the specified shell

Flags:
  -f, --format string   Output format (table, json, pretty) (default "table")
  -h, --help            help for mcp
  -p, --params string   JSON string of parameters to pass to the tool (for call command) (default "{}")

Use "mcp [command] --help" for more information about a command.

Transport Options

MCP Tools supports multiple transport methods for communicating with MCP servers:

Stdio Transport

Uses stdin/stdout to communicate with an MCP server via JSON-RPC 2.0. This is useful for command-line tools that implement the MCP protocol.

mcp tools npx -y @modelcontextprotocol/server-filesystem ~

HTTP SSE Transport

Uses HTTP and Server-Sent Events (SSE) to communicate with an MCP server via JSON-RPC 2.0. This is useful for connecting to remote servers that implement the legacy MCP protocol. Transport is automatically detected when the URL ends with /sse.

mcp tools http://localhost:3001/sse

# Example: Use the everything sample server
# docker run -p 3001:3001 --rm -it tzolov/mcp-everything-server:v1

Note: HTTP SSE currently supports only MCP protocol version 2024-11-05.

Streamable HTTP Transport (Recommended)

Uses streamable HTTP to communicate with an MCP server via JSON-RPC 2.0. This is the modern, recommended approach for connecting to remote servers that implement the MCP protocol. It supports both streaming responses and simple request/response patterns. This is the default transport for HTTP/HTTPS URLs.

# Default transport for HTTP URLs
mcp tools http://localhost:3000

# Streamable HTTP transport (auto-detected from URL)
mcp tools http://localhost:3000

# Examples with remote servers
mcp tools https://api.example.com/mcp
mcp tools https://ne.tools

Benefits of Streamable HTTP:

• Session Management: Supports stateful connections with session IDs
• Resumability: Can reconnect and resume interrupted sessions (when supported by server)
• Flexible Responses: Supports both streaming and direct JSON responses
• Modern Protocol: Uses the latest MCP transport specification

Output Formats

MCP Tools supports three output formats to accommodate different needs:

Table Format (Default)

mcp tools npx -y @modelcontextprotocol/server-filesystem ~

The default format now displays tools in a colorized man-page style:

read_file(path:str)
     Read the complete contents of a file from the file system.
read_multiple_files(paths:str[])
     Read the contents of multiple files simultaneously.
list_dir(path:str)
     Lists the contents of a directory.
write_file(path:str, content:str)
     Writes content to a file.
grep_search(pattern:str, [excludePatterns:str[]])
     Search files with pattern.
edit_file(edits:{newText:str,oldText:str}[], path:str)
     Edit a file with multiple text replacements

Key features of the format:

• Function names are displayed in bold cyan
• Required parameters are shown in green (e.g., path:str)
• Optional parameters are shown in yellow brackets (e.g., [limit:int])
• Array types are indicated with [] suffix (e.g., str[])
• Object types show their properties in curly braces (e.g., {prop1:type1,prop2:type2})
• Nested objects are displayed recursively (e.g., {notifications:{enabled:bool,sound:bool}})
• Type names are shortened for readability (e.g., str instead of string, int instead of integer)
• Descriptions are indented and displayed in gray
• Parameter order is consistent, with required parameters listed first

JSON Format (Compact)

mcp tools --format json npx -y @modelcontextprotocol/server-filesystem ~

Pretty JSON Format (Indented)

mcp tools --format pretty npx -y @modelcontextprotocol/server-filesystem ~

Commands

MCP Tools includes several core commands for interacting with MCP servers:

List Available Tools

mcp tools npx -y @modelcontextprotocol/server-filesystem ~

List Available Resources

mcp resources npx -y @modelcontextprotocol/server-filesystem ~

List Available Prompts

mcp prompts npx -y @modelcontextprotocol/server-filesystem ~

Call a Tool

mcp call read_file --params '{"path":"/path/to/file"}' npx -y @modelcontextprotocol/server-filesystem ~

Call a Resource

mcp call resource:test://static/resource/1 npx -y @modelcontextprotocol/server-everything -f json | jq ".contents[0].text"

or

mcp read-resource test://static/resource/1 npx -y @modelcontextprotocol/server-everything -f json | jq ".contents[0].text"

Call a Prompt

mcp get-prompt simple_prompt npx -y @modelcontextprotocol/server-everything -f json | jq ".messages[0].content.text"

Viewing Server Logs

When using client commands that make calls to the server, you can add the --server-logs flag to see the server logs related to your request:

# View server logs when listing tools
mcp tools --server-logs npx -y @modelcontextprotocol/server-filesystem ~

Output:

[>] Secure MCP Filesystem Server running on stdio
[>] Allowed directories: [ '/Users/fka/' ]
read_file(path:str)
     Read the complete contents of a file from the file system.
read_multiple_files(paths:str[])
     Read the contents of multiple files simultaneously.
... and the other tools available on this server

This can be helpful for debugging or understanding wh