Command Reference

This section is the CLI lookup entrypoint. Use it when you already know which command family you need and want exact syntax, options, or examples.

For AI agents, the preferred path is CLI mode: keep MCP behind 1mcp serve, then use instructions, inspect, and run as a progressive-disclosure workflow instead of exposing a broad tool surface directly in the agent loop.

If you are still trying to get a first setup working, use Quick Start before drilling into command details.

Quick Reference

Main Commands

• serve - Start the 1MCP server (default command)
• proxy - Start STDIO proxy to connect to running 1MCP HTTP server
• instructions - Show the CLI playbook and current server inventory
• inspect - List exposed servers or inspect a tool schema
• run - Call a tool through a running 1MCP server
• cli-setup - Install Codex or Claude bootstrap hooks and startup docs
• auth - Manage authentication profiles for secured servers
• app - Manage desktop application MCP configurations
• mcp - Manage MCP server configurations
• preset - Manage server presets for dynamic filtering

Global Options

All 1MCP commands support the following global options:

• --help, -h - Show help information
• --version - Show version information
• --config, -c <path> - Specify configuration file path
• --config-dir, -d <path> - Path to the config directory
• --cli-session-cache-path <path> - Path template for the run/inspect CLI session cache file

Environment Variables: All global options can be set via environment variables with the ONE_MCP_ prefix:

• ONE_MCP_CONFIG=/path/to/config.json
• ONE_MCP_CONFIG_DIR=/path/to/config/dir
• ONE_MCP_CLI_SESSION_CACHE_PATH=/tmp/1mcp/.cli-session.{pid}

Command-Specific Options

In addition to global options, each command may have specific options. Use --help with any command to see all available options:

npx -y @1mcp/agent mcp add --help
npx -y @1mcp/agent preset create --help
npx -y @1mcp/agent serve --help
npx -y @1mcp/agent inspect --help

Command Groups

CLI Workflow Commands

Use these commands together when you want an agent or terminal session to discover and call tools through a running 1mcp serve instance.

npx -y @1mcp/agent instructions
npx -y @1mcp/agent inspect context7
npx -y @1mcp/agent inspect context7/query-docs
npx -y @1mcp/agent run context7/query-docs --args '{"libraryId":"/mongodb/docs","query":"aggregation pipeline"}'

• instructions - Print the CLI playbook and current servers
• inspect - Discover tools and inspect schemas
• run - Execute a tool call
• cli-setup - Install Codex or Claude bootstrap files
• auth - Manage authentication profiles for secured servers

Use this group when an agent or operator is already working against a running 1mcp serve instance.

Why These Commands Exist

• Direct MCP is still the backend interoperability layer
• CLI mode is the preferred frontend workflow for agents
• instructions gives a compact inventory instead of a broad direct starting surface
• inspect narrows discovery to one server and one tool
• run executes only after schema confirmation

App Commands

Manage desktop application MCP configurations. Consolidate MCP servers from various desktop applications into 1MCP.

npx -y @1mcp/agent app consolidate claude-desktop    # Consolidate Claude Desktop servers
npx -y @1mcp/agent app restore claude-desktop        # Restore original configuration
npx -y @1mcp/agent app list                          # List supported applications

MCP Commands

Manage MCP server configurations within your 1MCP instance.

npx -y @1mcp/agent mcp add myserver --type=stdio --command=node --args=server.js
npx -y @1mcp/agent mcp list                       # List configured servers
npx -y @1mcp/agent mcp status                     # Check server status

Preset Commands

Manage server presets for dynamic filtering and context switching.

npx -y @1mcp/agent preset create dev --filter "web,api,database"
npx -y @1mcp/agent preset list                    # List all presets
npx -y @1mcp/agent preset show development        # Show preset details
npx -y @1mcp/agent preset edit staging           # Edit preset configuration

Serve Command

Start the 1MCP server with various configuration options.

npx -y @1mcp/agent serve                            # Start with default settings
npx -y @1mcp/agent serve --port=3052                # Start on custom port
npx -y @1mcp/agent serve --transport=stdio          # Use stdio transport

Proxy Command

Start STDIO proxy to connect MCP clients that only support STDIO transport to a running 1MCP HTTP server.

npx -y @1mcp/agent proxy                            # Auto-discover and connect
npx -y @1mcp/agent proxy --url http://localhost:3051/mcp  # Connect to specific URL
npx -y @1mcp/agent proxy --filter "web,api"         # Connect with tag filtering

Agent Bootstrap

Use cli-setup when you want Codex or Claude sessions to start with the 1MCP bootstrap docs and hooks already configured.

npx -y @1mcp/agent cli-setup --codex
npx -y @1mcp/agent cli-setup --claude --scope repo --repo-root .

When to Leave This Section

If you need learning or setup guidance instead of exact command behavior, go to:

1. Installation Guide - Install 1MCP Agent
2. Quick Start - Basic setup and first server
3. Instructions Command - Start the CLI workflow with the current server inventory
4. Inspect Command - Discover tools and inspect schemas
5. Run Command - Execute a tool call through the running server

Examples

Basic Usage

# Start 1MCP server
npx -y @1mcp/agent serve

# Print the current CLI playbook and server inventory
npx -y @1mcp/agent instructions

# Inspect one server, then one tool
npx -y @1mcp/agent inspect filesystem
npx -y @1mcp/agent inspect filesystem/read_file

# Run the inspected tool
npx -y @1mcp/agent run filesystem/read_file --args '{"path":"./README.md"}'

Advanced Usage

# Start with custom configuration
npx -y @1mcp/agent serve --config=/custom/path/config.json --port=3052

# Add HTTP-based MCP server
npx -y @1mcp/agent mcp add remote-api --type=http --url=https://api.example.com/mcp

# Install Codex bootstrap docs and hooks
npx -y @1mcp/agent cli-setup --codex

# Inspect through a preset with JSON output
npx -y @1mcp/agent inspect filesystem --preset development --format json

# Run a tool while overriding the session cache path
ONE_MCP_CLI_SESSION_CACHE_PATH=/tmp/1mcp/.cli-session.{pid} \
  npx -y @1mcp/agent run filesystem/read_file --args '{"path":"./README.md"}'

Environment Variables

All command-line options can also be set via environment variables with the ONE_MCP_ prefix:

export ONE_MCP_PORT=3052
export ONE_MCP_HOST=0.0.0.0
export ONE_MCP_CONFIG=/custom/config.json

Configuration Files

1MCP Agent uses JSON configuration files to store server definitions and settings. See the Configuration Guide for detailed information about configuration file formats and options.