### Basic Server Installation Example

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/commands/mcp/install.md

Installs the latest available version of the 'filesystem' server from the registry. This is a common use case for getting started with a server.

```bash
npx -y @1mcp/agent mcp install filesystem
```

--------------------------------

### Get Manual Setup Instructions

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/commands/app/consolidate.md

Instead of performing automatic consolidation, use the `--manual-only` option to display manual setup instructions for a specific application. This example is for Cherry Studio.

```bash
# Get manual setup instructions for an app
npx -y @1mcp/agent app consolidate cherry-studio --manual-only
```

--------------------------------

### Install and Start 1MCP Runtime

Source: https://github.com/1mcp-app/agent/blob/main/README.md

Install the global package, add an upstream server, and initiate the server process.

```bash
npm install -g @1mcp/agent
1mcp mcp add context7 -- npx -y @upstash/context7-mcp
1mcp serve
```

--------------------------------

### Setup Development Environment

Source: https://github.com/1mcp-app/agent/blob/main/CONTRIBUTING.md

Commands to clone the repository and install dependencies for local development.

```bash
git clone https://github.com/YOUR-USERNAME/agent.git
cd agent
pnpm install
```

--------------------------------

### Setup Development Environment Workflow

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/reference/internal-tools/index.md

An example AI assistant workflow demonstrating the steps to discover, install, and enable development tools and servers using MCP internal tools. It includes error handling for registry availability and verification of installed servers.

```javascript
// Example AI assistant workflow for setting up a development environment

async function setupDevelopmentEnvironment() {
  // 1. Discover available servers
  const registryStatus = await mcp_registry_status();
  if (!registryStatus.isAvailable) {
    throw new Error('Registry not available');
  }

  // 2. Search for development tools
  const devTools = await mcp_search({
    query: 'development debugging tools',
    category: 'development',
  });

  // 3. Install required servers
  const installations = [];
  for (const server of devTools.results) {
    const installResult = await mcp_install({
      name: server.name,
      version: server.recommendedVersion,
    });
    installations.push(installResult);
  }

  // 4. Verify installation
  const serverList = await mcp_list();
  const installedServers = serverList.servers.filter((server) => server.status === 'running');

  // 5. Enable servers as needed
  for (const server of installedServers) {
    if (server.disabled) {
      await mcp_enable({ name: server.name });
    }
  }

  return {
    installed: installations.length,
    running: installedServers.length,
    servers: installedServers,
  };
}
```

--------------------------------

### Launch Interactive Installation Wizard

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/commands/mcp/install.md

Use this command to start the interactive installation wizard when no server name is provided. It defaults to interactive mode.

```bash
npx -y @1mcp/agent mcp install
```

--------------------------------

### Integrate Registry with MCP Commands

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/commands/registry/index.md

Examples showing how registry search commands can be piped into MCP install commands, and how to check for updates.

```bash
# These are equivalent:
npx -y @1mcp/agent registry search filesystem
npx -y @1mcp/agent mcp install --search filesystem
```

```bash
# Install from registry search results
npx -y @1mcp/agent registry search database | head -5 | xargs -I {} npx -y @1mcp/agent mcp install {}
```

```bash
# Check updates for all installed servers
npx -y @1mcp/agent registry updates --installed
```

--------------------------------

### Install Repo-Local Claude Setup

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/commands/cli-setup.md

Use this command to install setup files for Claude specifically within the current repository. This is useful for project-specific configurations.

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

--------------------------------

### Setup 1MCP Agent for Development

Source: https://github.com/1mcp-app/agent/blob/main/docs/public/llms-full.txt

Clone the repository, install dependencies, and build the agent for local development. Requires Git and pnpm.

```bash
git clone https://github.com/1mcp-app/agent.git
cd agent
pnpm install
pnpm build
```

--------------------------------

### Login Command Examples

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/commands/auth.md

Examples showing how to save tokens via direct flags, pipes, or after adding a target.

```bash
# Save token for the local runtime context
npx -y @1mcp/agent auth login --context local --token mytoken

# Pipe token from a secret manager
op read "op://vault/1mcp/token" | npx -y @1mcp/agent auth login --context prod

# Save token for a named remote target
npx -y @1mcp/agent target add prod https://1mcp.example.com
npx -y @1mcp/agent auth login --context prod --token mytoken
```

--------------------------------

### Preview Filesystem Installation

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/commands/mcp/install.md

This command shows a preview of the installation process for the 'filesystem' server without making any changes. The output indicates what would be installed.

```bash
npx -y @1mcp/agent mcp install filesystem --dry-run
```

--------------------------------

### Production Configuration Example (Environment Variable)

Source: https://github.com/1mcp-app/agent/blob/main/docs/zh/reference/pagination.md

A sample production setup using an environment variable to enable pagination, ensuring compatibility with CI/CD pipelines.

```bash
export ONE_MCP_PAGINATION=true
npx -y @1mcp/agent --config production.json
```

--------------------------------

### Configure Async Loading via CLI

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/guide/advanced/fast-startup.md

Example command to start the 1MCP agent with async loading enabled and a custom batch delay.

```bash
npx -y @1mcp/agent --config mcp.json --enable-async-loading \
  --async-notify-on-snapshot \
  --async-batch-delay 250
```

--------------------------------

### Install All Database Servers

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/commands/registry/search.md

Searches for all servers in the 'database' category and installs them individually.

```bash
# Install all database servers
registry search --category=database --output=list |
  xargs -n1 npx -y @1mcp/agent mcp install
```

--------------------------------

### Install Global Codex Setup

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/commands/cli-setup.md

Use this command to install setup files for Codex in the global scope. This prepares your environment for Codex integration with 1MCP.

```bash
npx -y @1mcp/agent cli-setup --codex
```

--------------------------------

### Install and Run 1MCP Agent

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/index.md

Install the 1MCP agent globally, add an MCP context, start the unified runtime, and set up CLI mode for agents. This provides a quick setup for agent workflows.

```bash
npm install -g @1mcp/agent
1mcp mcp add context7 -- npx -y @upstash/context7-mcp
1mcp serve
```

```bash
1mcp cli-setup --codex
# or
1mcp cli-setup --claude --scope repo --repo-root .
```

```bash
1mcp instructions
1mcp inspect context7
1mcp inspect context7/query-docs
1mcp run context7/query-docs --args '{"libraryId":"/mongodb/docs","query":"aggregation pipeline"}'
```

--------------------------------

### Install Both Global and Repo-Local Codex Setup

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/commands/cli-setup.md

This command installs setup files for Codex in both global and repository-local scopes. Use this for comprehensive setup across your user environment and specific projects.

```bash
npx -y @1mcp/agent cli-setup --codex --scope all
```

--------------------------------

### Install and Configure 1MCP Agent Locally

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/guide/integrations/claude-desktop.md

Install the 1MCP agent, add MCP servers with tags, create a preset for Claude Desktop, start the HTTP server, and preview/consolidate the configuration.

```bash
# 1. Install 1MCP agent
npm install -g @1mcp/agent

# 2. Add some useful MCP servers (with tags for filtering)
npx -y @1mcp/agent mcp add context7 --tags=documentation,docs -- npx -y @upstash/context7-mcp
npx -y @1mcp/agent mcp add sequential --tags=thinking,analysis -- npx -y @modelcontextprotocol/server-sequential-thinking
npx -y @1mcp/agent mcp add playwright --tags=browser,testing -- npx -y @playwright/mcp

# 3. Create a preset for Claude Desktop
npx -y @1mcp/agent preset create claude-desktop --filter "documentation OR thinking OR browser"

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

# 5. In another terminal, preview consolidation
npx -y @1mcp/agent app consolidate claude-desktop --dry-run

# 6. Consolidate Claude Desktop configuration
npx -y @1mcp/agent app consolidate claude-desktop

# 7. Restart Claude Desktop

# 8. Verify tools are available in Claude Desktop
npx -y @1mcp/agent mcp status  # Check server health
```

--------------------------------

### Custom Tool Examples Configuration

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/reference/instructions-template/variables.md

Provides an example of how to configure custom tool examples in JSON format. This allows for documentation of specific tools with their descriptions.

```json
{
  "examples": [
    {
      "name": "custom_1mcp_analyze",
      "description": "Analyze data through custom server"
    },
    {
      "name": "monitor_1mcp_check",
      "description": "Check system health through monitoring server"
    }
  ]
}
```

--------------------------------

### Standard Syntax Examples

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/commands/mcp/add.md

Examples of adding local filesystem servers and remote HTTP servers using explicit type definitions.

```bash
# Add a local filesystem server
npx -y @1mcp/agent mcp add files --type=stdio --command="mcp-server-fs" --args="--root,./"

# Add a remote HTTP server with tags
npx -y @1mcp/agent mcp add remote-api --type=http --url="https://api.example.com/mcp" --tags="api,prod"
```

--------------------------------

### Install Server by Name

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/commands/mcp/install.md

Install a specific server from the registry by providing its name. This command fetches the latest version by default.

```bash
npx -y @1mcp/agent mcp install <server-name>
```

--------------------------------

### Development Setup with Pagination

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/reference/pagination.md

Use this command for quick development setups, enabling pagination and setting the log level to debug for detailed output.

```bash
# Quick development with pagination
npx -y @1mcp/agent --config dev.json --pagination --log-level debug
```

--------------------------------

### Security Configuration Examples

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/reference/health-check.md

Command-line examples for configuring health information detail levels across different deployment environments.

```bash
# Development environment
npx -y @1mcp/agent --config mcp.json --health-info-level full

# Staging environment
npx -y @1mcp/agent --config mcp.json --health-info-level basic

# Production environment (default minimal level is secure)
npx -y @1mcp/agent --config mcp.json
```

--------------------------------

### Install Specific Server Version

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/commands/registry/index.md

These commands demonstrate how to install specific major, minor, or exact versions of a server, as well as pre-release versions.

```bash
# Install specific major version
npx -y @1mcp/agent mcp install filesystem@1
```

```bash
# Install specific minor version
npx -y @1mcp/agent mcp install filesystem@1.2
```

```bash
# Install exact version
npx -y @1mcp/agent mcp install filesystem@1.2.0
```

```bash
# Install pre-release version
npx -y @1mcp/agent mcp install filesystem@2.0.0-beta.1
```

--------------------------------

### Install Top Database Server

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/commands/registry/search.md

Searches for the top database server, extracts its name, and installs it using the @1mcp/agent.

```bash
# Search and install top result
registry search database --limit=1 --output=json |
  jq -r '.results[0].name' |
  xargs npx -y @1mcp/agent mcp install
```

--------------------------------

### Status Command Examples

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/commands/auth.md

Examples for checking authentication status on local and remote contexts.

```bash
# Check the local runtime context
npx -y @1mcp/agent auth status --context local

# Check a named remote target
npx -y @1mcp/agent auth status --context prod
```

--------------------------------

### Install and Configure Systemd Service

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/guide/getting-started.md

Installs the 1MCP binary and registers it as a systemd service for automatic startup and management.

```bash
# First, install the binary system-wide (if not already done)
sudo curl -L -o /usr/local/bin/1mcp https://github.com/1mcp-app/agent/releases/latest/download/1mcp-linux-x64
sudo chmod +x /usr/local/bin/1mcp

# Create systemd service file
sudo tee /etc/systemd/system/1mcp.service << 'EOF'
[Unit]
Description=1MCP - Universal MCP Server Proxy
After=network.target

[Service]
Type=simple
User=$USER
WorkingDirectory=/home/$USER
ExecStart=/usr/local/bin/1mcp --config /etc/1mcp/mcp.json --port 3050 --enable-auth
Restart=always
RestartSec=5
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target
EOF

# Enable and start service
sudo systemctl daemon-reload
sudo systemctl enable 1mcp
sudo systemctl start 1mcp

# Check status
sudo systemctl status 1mcp
```

--------------------------------

### Install MCP Servers

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/commands/mcp/index.md

Install servers from the registry with automatic dependency resolution.

```bash
npx -y @1mcp/agent mcp install filesystem
npx -y @1mcp/agent mcp install --interactive
```

--------------------------------

### Search and Install MCP Servers

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/guide/essentials/server-management.md

Use these commands to search for available MCP servers in the registry and install them. The search command can filter by category, and results can be piped to the install command.

```bash
# Search for available servers
npx -y @1mcp/agent registry search --category=filesystem
```

```bash
# Install the filesystem server
npx -y @1mcp/agent mcp install filesystem
```

```bash
# Or use the interactive wizard
npx -y @1mcp/agent mcp wizard
```

```bash
# Install latest version
npx -y @1mcp/agent mcp install filesystem
```

```bash
# Install specific version
npx -y @1mcp/agent mcp install filesystem@1.2.0
```

```bash
# Install with configuration
npx -y @1mcp/agent mcp install git --repository /path/to/project
```

```bash
# Start interactive wizard
npx -y @1mcp/agent mcp wizard
```

```bash
# Start with predefined template
npx -y @1mcp/agent mcp wizard --template development
```

```bash
# Search for database servers
npx -y @1mcp/agent registry search database
```

```bash
# Install search results
npx -y @1mcp/agent registry search database --limit=3 --output=list | \
  xargs -n1 npx -y @1mcp/agent mcp install
```

--------------------------------

### Basic Server Search Example

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/commands/mcp/search.md

This example demonstrates how to search for servers related to 'database' using the 'mcp search' command. It filters servers based on the provided query.

```bash
npx -y @1mcp/agent mcp search database
```

--------------------------------

### Start 1mcp Serve and Proxy

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/commands/proxy.md

Demonstrates the typical usage pattern where `1mcp serve` is started in one shell, and `1mcp proxy` is initiated in another to connect to it.

```bash
# shell 1
1mcp serve

# shell 2
1mcp proxy
```

--------------------------------

### Example Output of Preset Test

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/commands/preset/test.md

This example shows the typical output when testing a preset, including matching servers and available tags in your configuration.

```bash
npx -y @1mcp/agent preset test development

🔍 Testing preset 'development':
   Matching servers: webserver, apiserver, devtools
   Available tags: web, api, database, development, testing, monitoring
```

--------------------------------

### Install MCP Server from Registry

Source: https://github.com/1mcp-app/agent/blob/main/docs/public/llms-full.txt

Install a specific MCP server package, such as '@modelcontextprotocol/server-filesystem', directly from the MCP registry.

```bash
1mcp mcp install @modelcontextprotocol/server-filesystem
```

--------------------------------

### Example Tool Usage

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/guide/custom-instructions-template.md

Provides examples of available tools, showing their name and a brief description. This helps users understand and utilize the aggregated capabilities.

```handlebars
{{#each examples}}
- `{{name}}` - {{description}}
{{/each}}
```

--------------------------------

### Tool Examples Iteration

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/reference/instructions-template/variables.md

Shows how to iterate over an array of tool examples to list available tools and their descriptions. This is used for generating tool documentation.

```text
Available tools:
{{#each examples}}
- `{{name}}`: {{description}}
{{/each}}
```

--------------------------------

### Example: Setting up Web Development Environment

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/guide/integrations/codex.md

Add a filesystem server, create a 'web-dev' preset, and set it as the active configuration.

```bash
# Web development
1mcp mcp add filesystem --tags=files,web -- npx -y @modelcontextprotocol/server-filesystem ./src
1mcp preset create web-dev --filter "files OR git OR web"
echo '{"preset": "web-dev"}' > .1mcprc
```

--------------------------------

### Example: Setting up Data Science Environment

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/guide/integrations/codex.md

Add a Python server, create a 'data-science' preset, and set it as the active configuration.

```bash
# Data science
1mcp mcp add python --tags=python,data -- npx -y @modelcontextprotocol/server-python
1mcp preset create data-science --filter "python OR database OR data"
echo '{"preset": "data-science"}' > .1mcprc
```

--------------------------------

### Preview Installation with Dry Run

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/commands/mcp/install.md

Use the --dry-run flag to see which servers and dependencies would be installed without making any actual changes to your configuration. This is useful for planning.

```bash
npx -y @1mcp/agent mcp install <server-name> --dry-run
```

--------------------------------

### Start development server

Source: https://github.com/1mcp-app/agent/blob/main/CONTRIBUTING.md

Launch the development server for local testing.

```bash
pnpm dev
```

--------------------------------

### Client-Aware Configuration Example

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/reference/mcp-templates/syntax.md

Dynamically configure server arguments and disable status based on client information. This example uses `transport.client.name` and `version` for customization.

```json
{
  "mcpTemplates": {
    "client-specific": {
      "command": "npx",
      "args": ["-y", "my-server", "--client", "{{transport.client.name}}", "--version", "{{transport.client.version}}"],
      "disabled": "{{#if (or (eq transport.client.name 'cursor') (eq transport.client.name 'claude-code'))}}false{{else}}true{{/if}}"
    }
  }
}
```

--------------------------------

### Set Up Development Environment Variables

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/guide/development.md

Copy the example environment file to `.env` to configure development-specific settings. This file controls logging, ports, authentication, and other runtime parameters.

```bash
cp .env.example .env
```

--------------------------------

### Start Codex in Project Directory

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/guide/integrations/codex.md

Navigates to your project directory and starts the Codex application. This ensures Codex loads the correct configuration, including the .1mcprc file for the 1MCP proxy.

```bash
cd /path/to/my-project
codex
```

--------------------------------

### Example Preset Output

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/commands/preset/show.md

This is an example of the detailed output you can expect when using the `preset show` command. It includes basic information, client URL, tag query, server matching, and quick actions.

```text
┌─────────── Preset Details ────────────┐
│ 📋 development                        │
│ Strategy: OR logic - Match ANY tags   │
│ Description: Development servers      │
│ Created: 9/6/2025                     │
│                                       │
│ Client URL:                           │
│ http://127.0.0.1:3050/?preset=dev     │
│                                       │
│ Tag Query:                            │
│ {
│   "$or": [
│     { "tag": "web" },
│     { "tag": "api" }
│   ]
│ }
│                                       │
│ Matching Servers (2):                 │
│ • webserver, • apiserver              │
│                                       │
│ Quick Actions:
│ • Test: preset test development       │
│ • Edit: 1mcp preset edit dev         │
│ • URL:  preset url development        │
└───────────────────────────────────────┘
```

--------------------------------

### String Substring Extraction

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/reference/mcp-templates/syntax.md

Extract portions of a string using the `substring` helper. It supports specifying both start and end indices, or just a start index to get the remainder of the string.

```text
{{substring project.name 0 5}}    <!-- Characters 0-4 -->
```

```text
{{substring project.name 3}}      <!-- From character 3 to end -->
```

--------------------------------

### Start 1mcp Agent Server

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/guide/integrations/claude-desktop.md

Starts the 1mcp agent server on a specified port with HTTP transport and an external URL. This is the basic command to get the server running.

```bash
npx -y @1mcp/agent serve --transport http --port 3001 --external-url https://your-domain.com
```

--------------------------------

### Uninstall an MCP Server

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/commands/registry/index.md

Remove an installed MCP server, for example, 'filesystem', from the system.

```bash
npx -y @1mcp/agent mcp uninstall filesystem
```

--------------------------------

### Start 1MCP Runtime

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/guide/getting-started.md

Launch the 1MCP server using the binary or npx with a specified configuration file.

```bash
# Binary option:
1mcp serve --config ~/.config/1mcp/mcp.json --port 3050

# NPM option:
npx -y @1mcp/agent serve --config ~/.config/1mcp/mcp.json --port 3050

# You should see:
# ✅ Server is running on port 3050 with HTTP/SSE transport
# ✅ Connected to filesystem, memory servers
```

--------------------------------

### Background runtime startup output

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/commands/serve.md

Example output displayed to stderr when a background runtime is successfully started.

```text
Background runtime started.
PID: 48213
URL: http://localhost:3050/mcp
Log file: /home/me/.config/1mcp/logs/server.log
Servers: 3/5 ready
```

--------------------------------

### Development Configuration Example

Source: https://github.com/1mcp-app/agent/blob/main/docs/zh/reference/pagination.md

A sample command-line configuration for development, enabling pagination and setting the log level to debug for detailed output.

```bash
npx -y @1mcp/agent --config dev.json --pagination --log-level debug
```

--------------------------------

### Quick " -- " Pattern Syntax Examples

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/commands/mcp/add.md

Examples using the quick syntax pattern to auto-detect STDIO servers, including configuration for environment variables, restart policies, and working directories.

```bash
# Add server using " -- " pattern (type auto-detected as stdio)
npx -y @1mcp/agent mcp add airtable --env AIRTABLE_API_KEY=your_key -- npx -y airtable-mcp-server

# Add server with Windows command wrapper
npx -y @1mcp/agent mcp add my-server -- cmd /c npx -y @some/package

# Combine environment variables with " -- " pattern
npx -y @1mcp/agent mcp add context7 --env API_TOKEN=secret --tags=ai,tools -- npx -y @context7/server

# Add server with restart configuration
npx -y @1mcp/agent mcp add robust-server --type=stdio --command=node --args=unstable-server.js --restart-on-exit --max-restarts=5 --restart-delay=2000

# Add disabled server with custom working directory
npx -y @1mcp/agent mcp add dev-server --type=stdio --command=python --args=dev-server.py --cwd=/app/development --disabled
```

--------------------------------

### CLI Setup for Agent Sessions

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/guide/integrations/developer-tools.md

Commands to set up bootstrap documentation and hooks for agent sessions using the 1MCP CLI.

```bash
# Install Codex bootstrap docs and hooks
1mcp cli-setup --codex

# Install repo-local Claude bootstrap docs and hooks
1mcp cli-setup --claude --scope repo --repo-root .
```

--------------------------------

### Start 1MCP Server

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/guide/integrations/codex.md

Initiates the 1MCP server process, which aggregates MCP servers. This command is used for direct HTTP transport setups.

```bash
1mcp serve  # Start 1MCP server
```

--------------------------------

### Get Development Preset URL for Client Configuration

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/commands/preset/url.md

Shell script example to capture the development preset URL into a variable for use in client configuration.

```bash
# Get development preset URL
DEV_URL=$(npx -y @1mcp/agent preset url development)
echo "Configure your development client with: $DEV_URL"
```

--------------------------------

### Add MCP Servers with Tags

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/guide/integrations/codex.md

Registers MCP servers (e.g., filesystem, github) with specific tags for preset filtering. This command is part of the Quick Start setup.

```bash
# Add some MCP servers with tags for preset filtering
1mcp mcp add filesystem --tags=files,local -- npx -y @modelcontextprotocol/server-filesystem /tmp
1mcp mcp add github --tags=git,remote,collaboration -- npx -y @modelcontextprotocol/server-github
```

--------------------------------

### Install 1MCP Agent

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/guide/quick-start.md

Install the 1MCP agent globally using npm. Ensure Node.js 18+ is installed.

```bash
npm install -g @1mcp/agent
```

--------------------------------

### Workflow Integration Examples

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/commands/preset/list.md

Demonstrates a typical workflow using the 'preset list' command in conjunction with other preset management commands like 'show', 'test', and 'url'.

```bash
# 1. List all presets to see what's available
npx -y @1mcp/agent preset list

# 2. Show details for a specific preset
npx -y @1mcp/agent preset show production

# 3. Test a preset to see matching servers
npx -y @1mcp/agent preset test production

# 4. Generate URL for client configuration
npx -y @1mcp/agent preset url production
```

--------------------------------

### Install Specific Server Version

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/commands/mcp/install.md

Install a server by name and specify a particular version. This ensures you install a known compatible version.

```bash
npx -y @1mcp/agent mcp install <server-name>@<version>
```

--------------------------------

### Verify Agent Installation

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/guide/installation.md

Commands to verify the agent installation. Use the appropriate command based on whether you installed the binary or via NPM.

```bash
# Binary installation:
1mcp --version
```

```bash
# NPM installation:
npx @1mcp/agent --version
```

--------------------------------

### Install 1MCP Agent Globally

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/guide/integrations/codex.md

Installs the 1MCP Agent globally on your system, allowing for the use of the shorter `1mcp` command. This is the recommended installation method.

```bash
# Install globally for easier use (recommended)
npm install -g @1mcp/agent
```

--------------------------------

### Initialize Serena Project

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/guide/integrations/serena.md

Initialize Serena in your project directory to create the necessary configuration file ('.serena/project.yml') and build the initial symbol index for optimal performance.

```bash
cd /path/to/your/project
serena project create --index
```

--------------------------------

### Display Available Tools

Source: https://github.com/1mcp-app/agent/blob/main/docs/zh/reference/instructions-template/variables.md

List available tools with their names and descriptions. Requires an 'examples' array, where each item has 'name' and 'description' properties.

```text
可用工具:
{{#each examples}}
- `{{name}}`: {{description}}
{{/each}}
```

--------------------------------

### MCP Agent Install Command Error Handling

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/commands/mcp/install.md

Illustrates common error messages from the mcp install command, such as server not found, version unavailable, or already installed.

```bash
# Server not found
npx -y @1mcp/agent mcp install nonexistent-server
# Error: Server 'nonexistent-server' not found in registry
# Suggestions: filesystem, git, database, search
```

```bash
# Version not available
npx -y @1mcp/agent mcp install filesystem@99.99.99
# Error: Version 99.99.99 not available for 'filesystem'
# Available versions: 1.2.0, 1.1.0, 1.0.0
```

```bash
# Already installed
npx -y @1mcp/agent mcp install filesystem
# Error: Server 'filesystem' already installed
# Use --force to reinstall or mcp update to upgrade
```

--------------------------------

### Install dependencies

Source: https://github.com/1mcp-app/agent/blob/main/CONTRIBUTING.md

Install required project dependencies using pnpm.

```bash
pnpm install
```

--------------------------------

### Example: Creating Presets for Team Roles

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/guide/integrations/codex.md

Define separate presets for frontend and backend roles to facilitate team collaboration.

```bash
# Team collaboration - different presets per role
1mcp preset create frontend --filter "frontend OR ui OR design"
1mcp preset create backend --filter "backend OR database OR api"
```

--------------------------------

### Verbose Installation of Airtable Server

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/commands/mcp/install.md

Installs the 'airtable' server with verbose output enabled. This provides detailed logs of the installation process, including dependency resolution and download steps.

```bash
npx -y @1mcp/agent mcp install airtable --verbose
```

--------------------------------

### Use npx for 1MCP Agent

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/guide/integrations/codex.md

An alternative to global installation, this command executes the 1MCP Agent without requiring prior installation, useful for quick checks or environments where global installs are restricted.

```bash
# Alternative: Use npx (no installation required)
npx -y @1mcp/agent --version
```

--------------------------------

### Install 1MCP Binary

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/guide/getting-started.md

Download and install the 1MCP binary for Linux, macOS, or Windows.

```bash
# Linux:
curl -L -o 1mcp https://github.com/1mcp-app/agent/releases/latest/download/1mcp-linux-x64
sudo mv 1mcp /usr/local/bin/ && sudo chmod +x /usr/local/bin/1mcp
1mcp --help

# macOS:
curl -L -o 1mcp https://github.com/1mcp-app/agent/releases/latest/download/1mcp-darwin-arm64
sudo mv 1mcp /usr/local/bin/ && sudo chmod +x /usr/local/bin/1mcp
1mcp --help

# Windows (PowerShell):
Invoke-WebRequest -Uri "https://github.com/1mcp-app/agent/releases/latest/download/1mcp-win32-x64.exe" -OutFile "1mcp.exe"
.\1mcp.exe --help
```

--------------------------------

### Run the 1MCP serve command

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/commands/serve.md

Execute the serve command or the default command to start the 1MCP runtime.

```bash
1mcp serve [options]
1mcp [options]
```

--------------------------------

### Start the 1mcp runtime

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/commands/serve.md

Basic command to initiate the runtime environment.

```bash
1mcp serve
```

--------------------------------

### Install 1MCP Agent on macOS (Intel) via Binary

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/guide/installation.md

Installs the 1MCP agent on macOS Intel systems by downloading, extracting, and moving the binary to a system path. Verifies the installation with `--version`.

```bash
# Download and extract archive
curl -L -o 1mcp-darwin-x64.tar.gz https://github.com/1mcp-app/agent/releases/latest/download/1mcp-darwin-x64.tar.gz
tar -xzf 1mcp-darwin-x64.tar.gz
sudo mv 1mcp-darwin-x64 /usr/local/bin/1mcp
sudo chmod +x /usr/local/bin/1mcp

# Clean up
rm 1mcp-darwin-x64.tar.gz

# Verify installation
1mcp --version
```

--------------------------------

### Initialize Serena Project with Indexing

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/guide/integrations/serena.md

Initializes a Serena project configuration file (.serena/project.yml) and enables project indexing. This command should be run from within the project directory.

```bash
serena project create --index
```

--------------------------------

### Install 1MCP Agent on Linux (x64) via Binary

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/guide/installation.md

Installs the 1MCP agent on Linux x64 systems by downloading, extracting, and moving the binary to a system path. Verifies the installation with `--version`.

```bash
# Download and extract archive
curl -L -o 1mcp-linux-x64.tar.gz https://github.com/1mcp-app/agent/releases/latest/download/1mcp-linux-x64.tar.gz
tar -xzf 1mcp-linux-x64.tar.gz
sudo mv 1mcp-linux-x64 /usr/local/bin/1mcp
sudo chmod +x /usr/local/bin/1mcp

# Clean up
rm 1mcp-linux-x64.tar.gz

# Verify installation
1mcp --version
```

--------------------------------

### Basic Search for Filesystem Servers

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/commands/registry/search.md

A simple example demonstrating how to search for servers related to filesystem operations by providing a relevant keyword.

```bash
npx -y @1mcp/agent registry search filesystem
```

--------------------------------

### Complex Template Example

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/reference/instructions-template/variables.md

A comprehensive example combining various variables and Handlebars syntax to generate a detailed status report. It includes conditional sections for server connection status, instructions, and tool examples.

```text
# {{title}}

## Status: {{#if hasServers}}✅ Connected{{else}}⏳ Waiting{{/if}}

{{#if hasServers}}
**{{connectedServerCount}} {{connectedPluralServers}} connected**{{filterContext}}

### Servers
{{#each serverNames}}
- 🔧 {{this}}
{{/each}}

{{#if hasInstructionalServers}}
### Instructions
{{instructions}}

### Example Tools
{{#each examples}}
- `{{name}}` - {{description}}
{{/each}}

*Tools use pattern: `{{toolPattern}}`*
{{else}}
*Servers connected but no instructions provided yet*
{{/if}}
{{else}}
Waiting for server connections...
{{/if}}
```

--------------------------------

### Pull Request Title Examples

Source: https://github.com/1mcp-app/agent/blob/main/CONTRIBUTING.md

Examples of preferred and discouraged pull request title formats.

```text
Good: Add retry logic for MCP server connections
Bad: Fix bug
```

--------------------------------

### Start 1MCP Server

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/commands/index.md

Launch the 1MCP server with various configuration options for ports and transport.

```bash
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
```

--------------------------------

### Logout Command Examples

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/commands/auth.md

Examples for removing profiles or clearing local OAuth token references.

```bash
# Remove the local runtime context profile
npx -y @1mcp/agent auth logout --context local

# Remove a named remote target profile
npx -y @1mcp/agent auth logout --context prod

# Clear every local OAuth token reference without contacting a runtime
npx -y @1mcp/agent auth logout --context local --all-local
```

--------------------------------

### Install 1MCP Agent on macOS (ARM64) via Binary

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/guide/installation.md

Installs the 1MCP agent on macOS ARM64 (Apple Silicon) systems by downloading, extracting, and moving the binary to a system path. Verifies the installation with `--version`.

```bash
# Download and extract archive
curl -L -o 1mcp-darwin-arm64.tar.gz https://github.com/1mcp-app/agent/releases/latest/download/1mcp-darwin-arm64.tar.gz
tar -xzf 1mcp-darwin-arm64.tar.gz
sudo mv 1mcp-darwin-arm64 /usr/local/bin/1mcp
sudo chmod +x /usr/local/bin/1mcp

# Clean up
rm 1mcp-darwin-arm64.tar.gz

# Verify installation
1mcp --version
```

--------------------------------

### Runtime status output example

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/commands/serve.md

Example output format when querying the status of a supervised background runtime.

```text
Runtime Scope: /home/me/.config/1mcp
Status: running
Supervisor PID: 48190
Runtime PID: 48213
Restart attempt: 0
Last exit: none
Next retry: none
URL: http://localhost:3050/mcp
Started: 2026-06-26T00:00:00.000Z
Log file: /home/me/.config/1mcp/logs/server.log
Process: alive
Readiness (/health/ready): ready
```

--------------------------------

### Complete 1MCP Agent Configuration Example

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/guide/mcp-server-templates.md

A comprehensive example of an MCP configuration file, demonstrating various template definitions for project filesystem, team integration, conditional debugging, and client-aware servers.

```json
{
  "$schema": "https://docs.1mcp.app/schemas/v1.0.0/mcp-config.json",
  "version": "1.0.0",
  "templateSettings": {
    "validateOnReload": true,
    "failureMode": "graceful",
    "cacheContext": true
  },
  "mcpTemplates": {
    "project-filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "{{project.path}}"],
      "tags": ["filesystem", "project-local"],
      "disabled": "{{#if (eq transport.client.name 'claude-code')}}false{{else}}true{{/if}}"
    },
    "team-serena": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/oraios/serena",
        "serena",
        "start-mcp-server",
        "--project",
        "{{project.path}}",
        "--team",
        "{{project.custom.team}}",
        "--env",
        "{{project.environment}}"
      ],
      "env": {
        "PROJECT_ID": "{{project.custom.projectId}}",
        "GIT_BRANCH": "{{project.git.branch}}",
        "API_ENDPOINT": "{{project.custom.apiEndpoint}}"
      },
      "cwd": "{{project.path}}",
      "tags": ["filesystem", "search"]
    },
    "conditional-debug-server": {
      "command": "node",
      "args": ["{{project.path}}/debug-server.js"],
      "cwd": "{{project.path}}",
      "env": {
        "NODE_ENV": "{{project.environment}}",
        "DEBUG": "{{#if (eq project.environment 'development')}}true{{else}}false{{/if}}",
        "LOG_LEVEL": "{{#if (eq project.environment 'production')}}warn{{else}}debug{{/if}}"
      },
      "disabled": "{{#if (eq project.environment 'production')}}true{{else}}false{{/if}}",
      "tags": ["debug", "development"]
    },
    "client-aware-server": {
      "command": "npx",
      "args": [
        "-y",
        "my-custom-server",
        "--client",
        "{{transport.client.name}}",
        "--version",
        "{{transport.client.version}}"
      ],
      "env": {
        "CLIENT_NAME": "{{transport.client.name}}",
        "CLIENT_VERSION": "{{transport.client.version}}",
        "CONNECTION_ID": "{{transport.connectionId}}",
        "USER": "{{user.username}}"
      },
      "tags": ["client-aware", "custom"]
    }
  }
}
```

--------------------------------

### Start Docker Compose Service

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/guide/installation.md

Command to start the agent service defined in docker-compose.yml in detached mode.

```bash
docker compose up -d
```

--------------------------------

### Initialize Serena Project Configuration

Source: https://github.com/1mcp-app/agent/blob/main/docs/zh/guide/integrations/serena.md

Initialize a Serena project configuration in your project directory. This creates a .serena/project.yml file for project-specific settings.

```bash
# Navigate to the project
cd /path/to/your/project

# Initialize Serena project with an index
serena project create --index

# This will create a .serena/project.yml with project-specific settings
```

--------------------------------

### Start 1MCP HTTP Server and Consolidate Claude Desktop

Source: https://github.com/1mcp-app/agent/blob/main/docs/en/guide/integrations/claude-desktop.md

Start the 1MCP HTTP server in the background and then consolidate Claude Desktop to use the 1MCP proxy. A dry-run option is available to preview the consolidation before applying it.

```bash
npx -y @1mcp/agent serve &
```

```bash
npx -y @1mcp/agent app consolidate claude-desktop --dry-run  # Preview
npx -y @1mcp/agent app consolidate claude-desktop
```