Server Management Guide

This guide provides a comprehensive overview of managing MCP servers within your 1MCP instance using the recommended registry-based approach for server discovery, installation, and lifecycle management.

Registry-Based Workflow (Recommended)

The 1MCP registry provides a centralized repository for discovering, installing, and managing MCP servers with automatic dependency resolution and version management. This is the recommended approach for server management.

Quick Start

Install your first server from the registry:

# Search for available servers
npx -y @1mcp/agent registry search filesystem --type=npm --transport=stdio

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

# Or use interactive installation
npx -y @1mcp/agent mcp install --interactive

Registry Workflow

1. Discovery - Find servers that match your needs
2. Selection - Choose servers with version compatibility
3. Installation - Automatic dependency resolution and setup
4. Configuration - Server-specific customization
5. Management - Updates, removal, and lifecycle control

Registry Benefits

• Server Discovery - Browse and search across hundreds of MCP servers
• Version Management - Install specific versions with compatibility checking
• Dependency Resolution - Automatic installation of required dependencies
• Security Validation - Verified servers with integrity checks
• Update Management - Easy updates with change tracking
• Interactive Installation - Guided setup with the configuration wizard

Installation Methods

Direct Installation

Install servers by name from the registry:

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

# Install specific version
npx -y @1mcp/agent mcp install [email protected]

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

Interactive Wizard

Launch the configuration wizard for guided installation:

# Start interactive installation
npx -y @1mcp/agent mcp install --interactive

The wizard provides:

• Server browsing by category
• Step-by-step configuration
• Compatibility checking
• Best practice recommendations

Search and Install

Search the registry and install from results:

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

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

Transport Types

1MCP supports multiple transport types for connecting to MCP servers.

STDIO Transport

This is the most common transport for local MCP servers. 1MCP starts the server as a child process and communicates with it over standard input and standard output.

Use Cases: Running local tools like mcp-server-filesystem or mcp-server-git.

Configuration Example:

npx -y @1mcp/agent mcp add filesystem --type=stdio --command="mcp-server-filesystem" --args="--root ~/"

Key Features:

• Process Management: 1MCP manages the lifecycle of the server process.
• Environment Variables: Pass environment variables directly to the server process.
• Working Directory: Specify a custom working directory for the server.

Streamable HTTP Transport

This transport connects to an MCP server that is already running and exposed via an HTTP endpoint.

Use Cases: Connecting to remote MCP servers, or servers running as part of another application.

Configuration Example:

npx -y @1mcp/agent mcp add remote-api --type=http --url="https://mcp.example.com/"

Key Features:

• Remote Access: Connect to servers on your local network or the internet.
• Custom Headers: Add custom HTTP headers for authentication or other purposes.
• Endpoint Configuration: Configure the remote MCP endpoint and its request headers.

SSE Transport (Deprecated)

Server-Sent Events is a deprecated transport type. It is recommended to use the HTTP transport instead.

Configure a Custom Server in the Admin Console

Use Server inventory → Configure Custom Server when you need to add a static server or Template Server definition without editing the runtime configuration file. The shared form supports local STDIO, remote HTTP, and legacy SSE targets.

1. Choose Static or Template, then complete the transport-specific structured fields. STDIO requires a command; HTTP and SSE require a URL.
2. Add tags. Static targets can start enabled or disabled; Template definitions expose lifecycle controls and accept Handlebars expressions in fields rendered by the runtime.
3. For credentials, prefer Environment Secret Reference. The configuration stores the environment variable name or substitution expression instead of the secret material. Inline secret replacement is an advanced fallback.
4. Select Preview server. Preview validates the target, reports name conflicts, and redacts secret material. Static remote targets run a bounded connectivity check when applicable; Template preview validates structure and Request Context variable names without rendering context, connecting a backend, or creating an instance.
5. Review the diff and runtime facts, then explicitly confirm the source-specific create action.

Creation never replaces an existing static or Template Server target. If another writer creates the same name after preview, the confirmation is rejected and you must preview again. After a successful write, the Admin Console refreshes the inventory and opens the created source-qualified target. Template definitions become eligible after reload and create instances only when a later matching request supplies Request Context.

Server Configuration Details

Each server you define in 1MCP has a set of common configuration options:

• Name: A unique, human-readable name for the server (e.g., my-git-server).
• Transport: The transport type (stdio, http, or deprecated sse).
• Command/URL: The command to execute for stdio transports, or the URL for http and deprecated sse transports.
• Arguments: An array of command-line arguments for stdio servers.
• Environment: Key-value pairs of environment variables for stdio servers.
• Tags: A list of tags for organizing and filtering servers.
• Timeout: A connection timeout in milliseconds.
• Enabled/Disabled: A flag to enable or disable the server without deleting its configuration.

Server Management Workflow

Registry-Based Workflow (Recommended)

The modern workflow using the registry provides automatic dependency resolution and version management:

1. Discover Servers: Search the registry for servers that meet your needs.

   # Search for development servers
   npx -y @1mcp/agent registry search development --type=npm
   
   # Browse all available servers
   npx -y @1mcp/agent mcp install --interactive

2. Install Servers: Install servers with automatic configuration.

   # Install the filesystem server
   npx -y @1mcp/agent mcp install filesystem
   
   # Install specific version
   npx -y @1mcp/agent mcp install [email protected]

3. Verify Installation: Check that servers are properly installed and running.

   npx -y @1mcp/agent mcp list
   npx -y @1mcp/agent mcp status filesystem

4. Manage Updates: Keep servers updated with latest versions.

   # Inspect the installed server before updating
   npx -y @1mcp/agent mcp status filesystem
   
   # Update specific server
   npx -y @1mcp/agent mcp update filesystem

5. Manage Lifecycle: Enable, disable, or remove servers as needed.

   # Temporarily disable
   npx -y @1mcp/agent mcp disable filesystem
   
   # Re-enable
   npx -y @1mcp/agent mcp enable filesystem
   
   # Remove with backup
   npx -y @1mcp/agent mcp uninstall filesystem

Manual Configuration Workflow (Advanced)

For custom servers not available in the registry:

1. Add Server Manually: Configure server details manually.

   npx -y @1mcp/agent mcp add custom-server --type=stdio --command="node server.js"

2. Configure Settings: Set server-specific options.

   npx -y @1mcp/agent mcp update custom-server --tags=custom,experimental --args="--port=3000"

The registry-based approach is recommended for most users, with manual configuration reserved for custom or proprietary servers.

Best Practices

Configuration

• Use Descriptive Names: Give your servers clear, descriptive names.
• Use Tags for Organization: Apply a consistent tagging strategy to easily filter and manage your servers. Common tag categories include environment (dev, prod), function (database, files), and priority (critical, optional).
• Set Appropriate Timeouts: Configure timeouts based on the expected responsiveness of the server. Local servers can have shorter timeouts than remote ones.

Security

• Validate Server Sources: Only add MCP servers from trusted sources.
• Manage Secrets: Use environment variables to pass secrets like API keys to your servers. Avoid hardcoding them in your configuration.
• Limit Permissions: Run stdio servers with the minimum required permissions.