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.
Client startup hooks deliver runtime guidance through bootstrap. Fetch instructions separately only when guidance is missing or needs refreshing. For checkout selection and caller credentials, see Project and owner options.
Examples use the installed 1mcp command. Follow Installation to add it to PATH; the installation guide also documents npx as an alternative.
Quick Reference
Main Commands
serve- Start the 1MCP server (default command)proxy- Start STDIO proxy to connect to running 1MCP HTTP serverinstructions- Show the CLI playbook and current server inventoryinspect- List exposed servers or inspect a tool schemarun- Call a tool through a running 1MCP servercli-setup- Install Codex or Claude bootstrap hooks and startup docsproject- Prepare backends and release, drain, inspect, or resume checkout admissionauth- Manage authentication profiles for secured serverstarget- Manage verified Runtime Target Contextsadmin- Manage CLI Admin sessions for Runtime Target Contextsapp- Manage desktop application MCP configurationsmcp- Manage MCP server configurationspreset- Manage server presets for dynamic filteringtelemetry- Inspect, enable, disable or reset local product usage collection
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 therun/inspectCLI session cache file; supports{pid}and{scope}
Environment Variables: All global options can be set via environment variables with the ONE_MCP_ prefix:
ONE_MCP_CONFIG=/path/to/config.jsonONE_MCP_CONFIG_DIR=/path/to/config/dirONE_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:
1mcp mcp add --help
1mcp preset create --help
1mcp serve --help
1mcp inspect --helpCommand Groups
CLI Workflow Commands
For a standalone terminal session, use these commands to discover and call tools through a running 1mcp serve instance. In a hooked agent session, use the guidance delivered by bootstrap and run instructions only when guidance is missing or needs refreshing. With a named or implicitly discovered local runtime, supported Codex sessions resolve their owner and assigned project automatically. Claude and hosts without automatic owner lookup add their own bootstrap --project-owner <own-file> to each call. Each worker uses its own startup context and credential.
1mcp instructions
1mcp inspect context7
1mcp inspect context7/query-docs
1mcp 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
- wait - Wait for configured static servers to become connected and available
- project prepare - Inspect readiness and manage checkout preparation jobs
- project lifecycle - Release caller bindings, inspect blockers, drain and resume checkout admission
- 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
instructionsgives a compact inventory instead of a broad direct starting surfaceinspectnarrows discovery to one server and one toolrunexecutes only after schema confirmation
App Commands
Manage desktop application MCP configurations. Consolidate MCP servers from various desktop applications into 1MCP.
1mcp app consolidate claude-desktop # Consolidate Claude Desktop servers
1mcp app restore claude-desktop # Restore original configuration
1mcp app list # List supported applicationsMCP Commands
Manage MCP server configurations within your 1MCP instance.
1mcp mcp add myserver --type=stdio --command=node --args=server.js
1mcp mcp list # List configured servers
1mcp mcp status # Check server status
1mcp mcp tools list filesystem --disabledPreset Commands
Manage server presets for dynamic filtering and context switching.
1mcp preset create dev --filter "web,api,database"
1mcp preset list # List all presets
1mcp preset show development # Show preset details
1mcp preset edit staging # Edit preset configurationServe Command
Start the 1MCP server with various configuration options.
1mcp serve # Start with default settings
1mcp serve --port=3052 # Start on custom port
1mcp serve --transport=stdio # Use stdio transportProxy Command
Start STDIO proxy to connect MCP clients that only support STDIO transport to a running 1MCP HTTP server.
1mcp proxy # Auto-discover and connect
1mcp proxy --url http://localhost:3051/mcp # Connect to specific URL
1mcp proxy --filter "web,api" # Connect with tag filteringRuntime Targets and Admin Sessions
Use a named target when a remote runtime needs saved bearer or Admin credentials.
1mcp target add prod https://mcp.example.com/mcp --use
1mcp auth login --context prod --token "$TOKEN"
1mcp instructions --context prod
1mcp admin login --context prod --username operator- Runtime Target Contexts - Add, verify, import, and select named targets
- Admin Commands - Bootstrap, login, check, and revoke Admin sessions
Agent Bootstrap
Use cli-setup when you want Codex or Claude sessions to start with the 1MCP bootstrap docs and hooks already configured.
1mcp cli-setup --codex
1mcp 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:
- Installation Guide - Install 1MCP Agent
- Quick Start - Basic setup and first server
- Instructions Command - Start the CLI workflow with the current server inventory
- Inspect Command - Discover tools and inspect schemas
- Run Command - Execute a tool call through the running server
Examples
Basic Usage
# Start 1MCP server
1mcp serve
# Print the current CLI playbook and server inventory
1mcp instructions
# Inspect one server, then one tool
1mcp inspect filesystem
1mcp inspect filesystem/read_file
# Run the inspected tool
1mcp run filesystem/read_file --args '{"path":"./README.md"}'Advanced Usage
# Start with custom configuration
1mcp serve --config=/custom/path/config.json --port=3052
# Add HTTP-based MCP server
1mcp mcp add remote-api --type=http --url=https://api.example.com/mcp
# Install Codex bootstrap docs and hooks
1mcp cli-setup --codex
# Inspect through a preset with JSON output
1mcp 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} \
1mcp 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.jsonConfiguration 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.
