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

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

### Setup Development Environment

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

Install dependencies and copy the example environment file. This is required before running other development commands.

```bash
pnpm install
cp .env.example .env  # Required for development
```

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

### 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 1MCP and Start Runtime

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

Install the 1MCP agent globally, add an upstream MCP server, and start the unified runtime.

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

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

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

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

### 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,
  };
}
```

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

### Example: Project-Specific Config Directory

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

Demonstrates using a project-specific directory for agent configuration, enabling isolated setups.

```bash
# Use a project-specific config directory
npx -y @1mcp/agent --config-dir ./project-config
```

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

### Start 1MCP Agent (Binary)

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

Use this command to start the 1MCP agent using its binary installation. Ensure the configuration file path and port are correctly specified.

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

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

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

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

### Start 1MCP Agent (NPM)

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

Use this command to start the 1MCP agent via NPM. This is an alternative to the binary installation. Ensure the configuration file path and port are correctly specified.

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

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

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

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

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

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

### Start the 1MCP Runtime

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

This is the most basic way to start the 1MCP runtime. It uses default configurations and settings.

```bash
1mcp serve
```

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

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

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

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

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

### 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"
    }
  ]
}
```

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

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

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

### Start 1MCP Agent with Authentication (Binary)

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

Enable authentication for your 1MCP agent using the binary installation. This command starts the server with OAuth 2.1 endpoints enabled.

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

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

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

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

### Start Runtime for Direct HTTP MCP Clients

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

Configures the runtime to listen on a specific host and port, making it accessible to MCP-native clients via HTTP. The example shows how to point a client to the runtime.

```bash
1mcp serve --host 0.0.0.0 --port 3051
```

```text
http://127.0.0.1:3051/mcp?app=cursor
```

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

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

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

### 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 Server

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

Start the 1MCP server with default settings, a custom port, or specific transport.

```bash
npx -y @1mcp/agent serve                            # Start with default settings
```

```bash
npx -y @1mcp/agent serve --port=3052                # Start on custom port
```

```bash
npx -y @1mcp/agent serve --transport=stdio          # Use stdio transport
```

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

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

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

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

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

### 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}}
```

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

### Install Project Dependencies

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

Install all necessary project dependencies using pnpm. This command should be run after cloning the repository.

```bash
pnpm install
```

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

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

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

### Production Deployment Security Configuration Examples

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

Examples of command-line arguments for setting the health information detail level during 1MCP agent deployment. Use 'basic' or 'minimal' for public-facing 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
```

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

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

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

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

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

### 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        │
└───────────────────────────────────────┘
```

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

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

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

### Setting up 1MCP Agent Development Environment

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

Clone the repository, install dependencies using pnpm, and enable platform-specific path configurations in `src/utils/appPresets.ts` before building.

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

# Enable Platform Paths
# Edit src/utils/appPresets.ts
# Uncomment your platform's path configurations
# Build: pnpm build
```

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

### 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}}
```

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

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

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

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

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

### Complete MCP Server Configuration Example

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

A comprehensive example demonstrating various configuration options for an MCP server, including command, arguments, environment variables, filtering, restart settings, and timeouts.

```json
{
  "mcpServers": {
    "production-server": {
      "command": "node",
      "args": ["dist/server.js"],
      "cwd": "/app",

      "inheritParentEnv": true,
      "envFilter": ["PATH", "HOME", "USER", "NODE_*", "NPM_*", "!SECRET_*", "!KEY_*", "!BASH_FUNC_*"],
      "env": {
        "NODE_ENV": "production",
        "API_KEY": "${PROD_API_KEY}",
        "DB_URL": "${DATABASE_CONNECTION}",
        "LOG_LEVEL": "info"
      },
      "restartOnExit": true,
      "maxRestarts": 3,
      "restartDelay": 1500,
      "tags": ["production", "api"],
      "connectionTimeout": 10000,
      "requestTimeout": 30000
    }
  }
}
```

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

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

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

### Install MCP Servers from Registry

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

Install MCP servers from the 1MCP registry. Supports automatic dependency resolution and version management, or interactive installation.

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

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

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

### Basic 1MCP Agent Command Usage

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

Demonstrates basic commands for starting the server, printing playbook and inventory, inspecting tools, and running a tool.

```bash
# 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"}'
```

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

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

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

### 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"
```

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

### Install 1MCP Binary and Create Systemd Service

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

Installs the 1MCP binary system-wide and sets up a systemd service file for automatic startup, management, and logging. Ensure the User and WorkingDirectory are set appropriately for your environment.

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

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

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

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

### Start Runtime with Specific Configuration File or Directory

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

Use the `--config` or `--config-dir` options to specify a custom configuration file or directory for the 1MCP runtime.

```bash
1mcp serve --config ./mcp.json
```

```bash
1mcp serve --config-dir ./config
```

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

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

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

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

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

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

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

### 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}}
```

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

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

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

### Install Specific Server Version

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

Installs a specific version (e.g., 1.2.0) of a server, such as the 'git' server.

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

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

### 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"]
    }
  }
}
```

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

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

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

### Add Server with Environment Variables and Tags

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

Adds a server using the quick syntax, combining environment variables and tags for organization and configuration.

```bash
npx -y @1mcp/agent mcp add context7 --env API_TOKEN=secret --tags=ai,tools -- npx -y @context7/server
```

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

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

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

### Verify 1MCP Agent Installation

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

Confirms that the 1MCP Agent has been successfully installed and is accessible via the command line.

```bash
1mcp --version
```

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

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

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

### Add Server with Windows Command Wrapper

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

Demonstrates adding a server that requires a Windows command wrapper, using 'cmd /c' to execute the command.

```bash
npx -y @1mcp/agent mcp add my-server -- cmd /c npx -y @some/package
```

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

### Creating a Preset with Backend and Development Filters

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

Create a preset named 'backend' that includes servers tagged with both 'backend' and 'development'.

```bash
1mcp preset create backend --filter "backend AND development"
```