### Install and Start 1MCP Servers (Bash)

Source: https://docs.1mcp.app/guide/integrations/codex

This snippet demonstrates how to add and start MCP servers for the 1MCP application. It includes adding filesystem and GitHub servers with specific tags, and then starting the 1MCP server in the background. It assumes 1MCP is installed globally; otherwise, `npx -y @1mcp/agent` should be used.

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

# Start 1MCP server in background
1mcp serve
```

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

### Install Servers using 1mcp Agent

Source: https://docs.1mcp.app/commands/registry/search

Demonstrates how to search for and install servers using the 1mcp agent. It includes examples for installing the top search result and all servers within a specific category like 'database'. Dependencies include `npx`, `@1mcp/agent`, `jq`, and `registry` CLI.

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

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

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

### Remote Setup with ngrok

Source: https://docs.1mcp.app/guide/integrations/claude-desktop

Guides through setting up 1MCP for remote access using ngrok. This involves installing the agent, adding servers, exposing the local server via ngrok, and configuring Claude Desktop with the external URL.

```bash
# 1. Install and configure 1MCP
npm install -g @1mcp/agent
npx -y @1mcp/agent mcp add context7 -- npx -y @upstash/context7-mcp
npx -y @1mcp/agent mcp add sequential -- npx -y @modelcontextprotocol/server-sequential-thinking

# 2. Expose via ngrok
ngrok http 3001

# 3. Start server, use the URL from ngrok
npx -y @1mcp/agent serve --transport http --port 3001 --external-url https://abc123.ngrok-free.app

# 4. Add connector in Claude Desktop:
#    - Name: "My 1MCP Server"
#    - URL: "https://abc123.ngrok-free.app/mcp" (use the URL from ngrok)

# 5. Verify tools are available in Claude Desktop
```

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

### Basic Usage Examples for 1MCP Agent

Source: https://docs.1mcp.app/commands

Illustrates fundamental commands for starting the 1MCP server, adding MCP servers, initiating the STDIO proxy, consolidating desktop application configurations, and checking server status.

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

# Add a new MCP server
npx -y @1mcp/agent mcp add filesystem --type=stdio --command=mcp-server-filesystem

# Start STDIO proxy for clients that only support STDIO
npx -y @1mcp/agent proxy --filter "filesystem,editing"

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

# Check status
npx -y @1mcp/agent mcp status
```

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

### Start 1MCP Agent Server (Bash)

Source: https://docs.1mcp.app/guide/quick-start

This bash command starts the 1MCP agent using the previously created `mcp.json` configuration file and specifies the port to listen on (3000). This is a crucial step for running the agent and making it available for client connections.

```bash
npx -y @1mcp/agent --config mcp.json --port 3000
```

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

### Development Setup with Pagination (Bash)

Source: https://docs.1mcp.app/reference/pagination

Provides a command-line example for setting up the 1MCP Agent in a development environment with pagination enabled and debug logging. This is useful for testing and troubleshooting.

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

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

### Local Setup: Add Servers, Create Preset, Serve, and Consolidate 1MCP for Claude Desktop

Source: https://docs.1mcp.app/guide/integrations/claude-desktop

This snippet demonstrates the recommended local setup for integrating 1MCP with Claude Desktop. It includes adding servers with tags, creating a preset for filtered access, starting the 1MCP HTTP server in the background, and consolidating the configuration with Claude Desktop. The `--dry-run` option allows previewing the consolidation before applying it.

```bash
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 preset create claude-desktop --filter "documentation OR thinking"

npx -y @1mcp/agent serve &

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

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

### 1MCP Configuration Example (JSON)

Source: https://docs.1mcp.app/reference/feature-comparison

A simple JSON configuration snippet demonstrating the ease of setting up 1MCP servers. It shows a basic structure for defining MCP server configurations, highlighting the minimal setup time compared to custom development.

```json
{
  "mcpServers": {
    "your-servers": "standard MCP configuration"
  }
}

```

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

### Set Up Development Environment Variables

Source: https://docs.1mcp.app/guide/development

Copies the example environment file to `.env` to configure the development environment for 1MCP Agent. This file contains settings for logging, ports, authentication, and configuration directories.

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

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

### Production Setup with Nginx

Source: https://docs.1mcp.app/guide/integrations/claude-desktop

Details the steps for a production setup using Nginx. This includes starting the 1MCP server with security options, configuring Nginx for HTTPS to HTTP proxying, and setting up Claude Desktop with OAuth credentials.

```bash
# 1. Start 1MCP server (bind to localhost for security)
npx -y @1mcp/agent serve --transport http --port 3001 --enable-auth --external-url https://your-domain.com

# 2. Configure nginx to proxy HTTPS to HTTP
# 3. Add connector in Claude Desktop:
#    - Name: "Production 1MCP"
#    - URL: "https://your-domain.com/mcp"
#    - Add OAuth credentials

# 4. Verify tools are available in Claude Desktop
```

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

### MCP Server Configuration (JSON)

Source: https://docs.1mcp.app/commands/mcp/install

Example JSON output representing the configuration of installed MCP servers. Includes server details, command arguments, tags, and registry metadata such as version and installation timestamp.

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"],
      "tags": ["filesystem", "files", "local"],
      "_registry": {
        "name": "filesystem",
        "version": "1.2.0",
        "installedAt": "2024-01-15T10:30:00Z",
        "source": "1mcp-registry"
      }
    }
  }
}
```

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

### Start 1MCP Agent Server (Bash)

Source: https://docs.1mcp.app/commands/serve

Demonstrates basic commands to start the 1MCP agent server. It covers starting with default settings, specifying a custom port, and using the stdio transport. These commands are executed using npx.

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

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

# Start with stdio transport
npx -y @1mcp/agent serve --transport=stdio
```

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

### Verify Server Installation with 1MCP Agent

Source: https://docs.1mcp.app/guide/essentials/server-management

Check if servers are installed and running correctly using the 'list' command to see all installed servers or the 'status' command for a specific server.

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

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

### Create Basic MCP Configuration (Bash)

Source: https://docs.1mcp.app/guide/quick-start

This snippet demonstrates how to create a basic `mcp.json` configuration file using a bash heredoc. This file defines the `mcpServers` with a `filesystem` type, specifying the command to run and its arguments. It also includes the `$schema` field for IDE support.

```bash
cat > mcp.json << 'EOF' \
{
  "$schema": "https://docs.1mcp.app/schemas/v1.0.0/mcp-config.json",
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "tags": ["local", "files"]
    }
  }
}
EOF
```

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

### Production Setup with Environment Variables (Bash)

Source: https://docs.1mcp.app/reference/pagination

Shows a command-line example for configuring the 1MCP Agent in a production environment using environment variables to enable pagination. This promotes secure and flexible configuration.

```bash
# Production with environment variables
export ONE_MCP_PAGINATION=true
npx -y @1mcp/agent --config production.json
```

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

### Start 1MCP Proxy with a Development Preset

Source: https://docs.1mcp.app/commands/proxy

Start the 1MCP agent proxy using a previously created development preset. This command loads the configuration defined in the 'dev' preset, simplifying the proxy setup for development purposes.

```bash
npx -y @1mcp/agent proxy --preset dev
```

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

### Format Examples List

Source: https://docs.1mcp.app/guide/custom-instructions-template

This Handlebars snippet demonstrates how to format a list of examples, displaying each example's name and description. It iterates over an 'examples' array and formats each item as a list item with the name in backticks.

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

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

### Create and Manage 1MCP Systemd Service

Source: https://docs.1mcp.app/guide/getting-started

This script installs the 1MCP binary, creates a systemd service file for it, and then enables and starts the service. It also includes commands to check the service's status. The service is configured to restart automatically if it fails.

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

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

### Remote Setup: Start 1MCP HTTP Server for Claude Desktop

Source: https://docs.1mcp.app/guide/integrations/claude-desktop

This snippet shows how to start the 1MCP HTTP server for remote integration with Claude Desktop. It includes options for development (without authentication) and production (with authentication enabled), specifying the transport, port, and external URL.

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

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

### Advanced Usage Examples for 1MCP Agent

Source: https://docs.1mcp.app/commands

Demonstrates advanced functionalities including starting the server with custom configurations, adding HTTP-based MCP servers, bulk consolidating applications, filtering servers by tags, and creating/using presets.

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

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

# Bulk consolidate multiple applications
npx -y @1mcp/agent app consolidate claude-desktop cursor vscode --yes

# Filter servers by tags with detailed information
ONE_MCP_LOG_LEVEL=debug npx -y @1mcp/agent mcp list --tags=prod,api

# Create and use presets for dynamic server selection
npx -y @1mcp/agent preset create production --filter "web AND database AND monitoring"
npx -y @1mcp/agent preset url production
```

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

### Start 1MCP Agent Proxy (Bash)

Source: https://docs.1mcp.app/index

This command initiates the 1MCP Agent proxy using Node Package Execute (npx). It requires a configuration file (mcp.json) and specifies the port to run on. This is the primary command to get the aggregated MCP server running.

```bash
# Start the proxy
npx -y @1mcp/agent --config mcp.json --port 3000
```

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

### Install 1MCP Agent via NPM (Bash)

Source: https://docs.1mcp.app/guide/getting-started

Demonstrates how to run the 1MCP Agent using `npx`, which avoids the need for a global installation. This is a convenient option if Node.js is already installed.

```bash
# 1MCP runs via npx - no global installation required
# Verify it works:
npx -y @1mcp/agent --help
```

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

### Configure Project for STDIO Transport (Bash)

Source: https://docs.1mcp.app/guide/quick-start

This snippet shows how to create a `.1mcprc` file for projects that only support STDIO transport. It sets a default preset named `my-setup` and includes the `$schema` field for IDE autocompletion. After creating this file, the `npx -y @1mcp/agent proxy` command can be used to connect to a running 1MCP server.

```bash
cat > .1mcprc << 'EOF' \
{
  "$schema": "https://docs.1mcp.app/schemas/v1.0.0/project-config.json",
  "preset": "my-setup"
}
EOF

# Now simply run:
npx -y @1mcp/agent proxy
```

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

### Install MCP Server (Bash)

Source: https://docs.1mcp.app/commands/mcp/install

Installs MCP servers from the 1MCP registry. Supports interactive installation, direct server installation by name, specific version installation, dry runs to preview changes, and forcing reinstallation. Dependencies are automatically resolved and versions managed.

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

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

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

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

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

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

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

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

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

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

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

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

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

### Install MCP Servers with Versioning (Bash)

Source: https://docs.1mcp.app/commands/registry

Demonstrates how to install MCP servers using the 'mcp install' command, showcasing different versioning strategies from latest stable to exact and pre-release versions. This command requires the '@1mcp/agent' to be installed.

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

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

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

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

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

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

### Configuration Examples

Source: https://docs.1mcp.app/reference/pagination

Provides example configurations for enabling pagination in development and production environments.

```APIDOC
## Configuration Examples

### Development Setup

Enable pagination with debug logging for development.

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

### Production Setup

Use environment variables for production configurations.

```bash
# Production with environment variables
export ONE_MCP_PAGINATION=true
npx -y @1mcp/agent --config production.json
```
```

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

### Start Codex in Project Directory (Bash)

Source: https://docs.1mcp.app/guide/integrations/codex

This bash snippet demonstrates navigating to the project directory and starting the Codex application. It's crucial to start Codex from the project root to ensure it correctly loads the `.1mcprc` configuration and other project-specific settings.

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

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

### Install MCP Servers using 1MCP Agent CLI

Source: https://docs.1mcp.app/guide/essentials/server-management

Commands to search for, install, and manage MCP servers using the 1MCP agent's command-line interface. Supports direct installation by name, specific versions, and interactive wizard-based setup.

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

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

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

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

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

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

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

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

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

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

### Build and Run 1MCP Agent Development Server

Source: https://docs.1mcp.app/guide/development

Builds the 1MCP Agent project and starts the development server. Requires the project to be cloned and dependencies installed. It involves copying an environment file and then running the development command.

```bash
# Copy the example environment file first
cp .env.example .env

# Then run the development server
pnpm dev
```

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

### JSON Schema for Project Configuration (JSON)

Source: https://docs.1mcp.app/guide/quick-start

This JSON snippet demonstrates the `$schema` property within a `.1mcprc` project configuration file. It specifies the schema URL for IDE support, allowing for autocompletion and validation. The example shows both the production URL and a local relative path option.

```json
"$schema": "./schemas/v1.0.0/project-config.json"
```

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

### Install Servers using 1MCP Agent

Source: https://docs.1mcp.app/guide/essentials/server-management

Install servers from the 1MCP registry with automatic dependency resolution. You can install a server by its name or a specific version.

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

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

### Workflow Integration: List, Show, Test, and URL (Bash)

Source: https://docs.1mcp.app/commands/preset/list

Demonstrates a typical workflow using preset commands. It shows how to list all presets, then retrieve details for a specific preset, test its matching servers, and finally generate a client configuration URL. This sequence helps in managing and utilizing presets effectively.

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

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

### Clone and Install 1MCP Agent Repository

Source: https://docs.1mcp.app/guide/development

Clones the 1MCP Agent repository from GitHub and installs project dependencies using pnpm. Ensure Git and pnpm are installed and configured.

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

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

### Basic Preset Show Examples (Bash)

Source: https://docs.1mcp.app/commands/preset/show

Demonstrates how to use the 'preset show' command to retrieve details for specific presets like 'development' and 'production'. These examples illustrate the command's basic syntax for accessing preset information.

```bash
# Show details for a specific preset
npx -y @1mcp/agent preset show development

# Show production preset information
npx -y @1mcp/agent preset show production
```

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

### Start 1MCP Server for Direct HTTP Transport

Source: https://docs.1mcp.app/guide/integrations/codex

Command to start the 1MCP server, which can then be connected to directly by Codex via HTTP. This is suitable for simpler setups but lacks advanced project-specific features.

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

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

### AI Assistant Workflow: Setting up Development Environment

Source: https://docs.1mcp.app/reference/internal-tools

This JSON snippet demonstrates an AI assistant workflow for setting up a development environment by searching for and installing necessary MCP servers like PostgreSQL and Git. It includes steps for discovery, installation, and listing enabled servers.

```json
[
  {
    "tool": "mcp_search",
    "arguments": {
      "query": "postgresql database"
    }
  },
  {
    "tool": "mcp_search",
    "arguments": {
      "query": "git repository"
    }
  },
  {
    "tool": "mcp_install",
    "arguments": {
      "serverName": "postgres",
      "version": "2.0.1"
    }
  },
  {
    "tool": "mcp_install",
    "arguments": {
      "serverName": "git",
      "version": "3.1.0"
    }
  },
  {
    "tool": "mcp_list",
    "arguments": {
      "filter": "enabled"
    }
  }
]
```

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

### Get Manual Setup Instructions with --manual-only

Source: https://docs.1mcp.app/commands/app/consolidate

Instead of performing automatic consolidation, this option displays manual setup instructions for the specified application. This is helpful when automatic consolidation is not possible or desired.

```bash
npx -y @1mcp/agent app consolidate cherry-studio --manual-only
```

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

### Example Project-Specific Presets (Bash)

Source: https://docs.1mcp.app/guide/integrations/codex

Bash commands demonstrating the creation of project-specific presets for web development and data science. It includes adding servers, creating presets with filters, and setting the active preset in .1mcprc.

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

# 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

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

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

### Configure 1MCP Agent Server (Bash)

Source: https://docs.1mcp.app/commands/serve

Illustrates how to start the 1MCP agent server using custom configuration files and setting the log level for debugging. These commands utilize npx to execute the agent.

```bash
# Use custom configuration file
npx -y @1mcp/agent serve --config=/path/to/config.json

# Start with debug logging
npx -y @1mcp/agent serve --log-level=debug
```

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

### Start 1MCP Server with Authentication for HTTP/SSE Clients

Source: https://docs.1mcp.app/commands/proxy

Start the 1MCP agent server with authentication enabled for HTTP/SSE clients. These clients can authenticate using OAuth. This setup is recommended for web-based clients that require secure connections.

```bash
# Start server WITH authentication for web clients
npx -y @1mcp/agent serve --port=3052 --enable-auth

# HTTP/SSE clients can authenticate via OAuth
curl "http://localhost:3052/mcp?app=cursor"
```

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

### Start 1MCP Agent (Bash)

Source: https://docs.1mcp.app/guide/getting-started

Commands to start the 1MCP Agent using either the binary or NPM option, specifying the configuration file and port. It also shows the expected output upon successful startup.

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

# NPM option:
npx -y @1mcp/agent --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
# 📋 OAuth Management Dashboard: http://localhost:3050/oauth
```

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

### Start 1MCP Server without Authentication for STDIO Clients

Source: https://docs.1mcp.app/commands/proxy

Start the 1MCP agent server without authentication enabled, specifically for STDIO clients like Claude Desktop. This ensures that these clients can connect without authentication issues. The proxy will work out of the box with this setup.

```bash
# Start server WITHOUT authentication for STDIO clients
npx -y @1mcp/agent serve --port=3051

# Start proxy (will work out of the box)
npx -y @1mcp/agent proxy
```

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

### Example Output of Preset Edit (Bash)

Source: https://docs.1mcp.app/commands/preset/edit

This example illustrates the typical output when using the 'preset edit' command, including the configuration directory, the preset being edited, and a success message upon completion. It also shows the resulting URL for accessing the preset.

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

📁 Config directory: /Users/user/.config/1mcp

📝 Editing preset: development
   Description: Development servers

[Interactive TUI opens with current configuration loaded]

✅ Preset 'development' updated successfully!
🔗 URL: http://127.0.0.1:3050/?preset=development
```

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

### GET /health/ready

Source: https://docs.1mcp.app/reference/health-check

Checks if the 1MCP Agent is ready to accept incoming requests. This is crucial for determining when a service can start receiving traffic after deployment or restart.

```APIDOC
## GET /health/ready

### Description
Readiness probe to determine if the service is ready to accept requests.

### Method
GET

### Endpoint
/health/ready

### Parameters
None

### Request Example
```bash
curl -X GET "http://your-agent-url/health/ready"
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the service readiness (`ready`).
- **timestamp** (string) - The time the readiness check was performed.
- **configuration** (object) - Agent configuration status.
  - **loaded** (boolean) - Indicates if the configuration is loaded.
  - **serverCount** (number) - Total number of servers configured.
  - **enabledCount** (number) - Number of enabled servers.
  - **disabledCount** (number) - Number of disabled servers.
  - **authEnabled** (boolean) - Indicates if authentication is enabled.
  - **transport** (string) - The transport protocol used.

#### Response Example
```json
{
  "status": "ready",
  "timestamp": "2025-01-30T12:00:00.000Z",
  "configuration": {
    "loaded": true,
    "serverCount": 3,
    "enabledCount": 2,
    "disabledCount": 1,
    "authEnabled": true,
    "transport": "http"
  }
}
```

#### Error Response (503)
- **status** (string) - `not_ready`
- **timestamp** (string) - The time the readiness check was performed.
```

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

### Troubleshooting Preset Issues (Bash)

Source: https://docs.1mcp.app/commands/preset/show

Examples showing how to use 'preset show' for troubleshooting. This includes reviewing a preset before use, debugging why a preset might not be working, and checking for syntax issues in the tag query or server matching.

```bash
# Review preset before using
npx -y @1mcp/agent preset show development

# Copy the Client URL for your MCP client configuration
# Use the Matching Servers info to verify correct servers are included

# Share preset details with team members
npx -y @1mcp/agent preset show team-production

# Team members can see exact configuration and matching servers

# Debug why a preset isn't working as expected
npx -y @1mcp/agent preset show problematic-preset

# Check the Tag Query section for syntax issues
# Review Matching Servers to see actual results
```

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

### Manage Server Updates with 1MCP Agent

Source: https://docs.1mcp.app/guide/essentials/server-management

Check for available updates for your installed servers or update a specific server to its latest version using the registry search and update commands.

```bash
# Check for available updates
npx -y @1mcp/agent registry search --updates

# Update specific server
npx -y @1mcp/agent mcp update filesystem
```

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

### 1MCP Agent Proxy Basic Usage Examples (Bash)

Source: https://docs.1mcp.app/commands/proxy

This section provides practical bash examples for using the 1MCP agent proxy command. It covers basic auto-discovery and connection, enabling debug logging for troubleshooting, specifying a custom configuration directory for server discovery, and implicitly using the project configuration file (.1mcprc) for settings.

```bash
# Auto-discover and connect to running 1MCP server
npx -y @1mcp/agent proxy
```

```bash
# Connect with debug logging
npx -y @1mcp/agent proxy --log-level=debug
```

```bash
# Use custom config directory for discovery
npx -y @1mcp/agent proxy --config-dir=./test-config
```

```bash
# Use project configuration file (.1mcprc)
npx -y @1mcp/agent proxy
```

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

### Start 1MCP Server

Source: https://docs.1mcp.app/guide/integrations/app-consolidation

This command initiates the 1MCP server, which is required for certain operations like validating URLs with the 'consolidate' command. Ensure the server is running before performing related tasks.

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

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

### Build and Run 1mcp-app Agent from Source

Source: https://docs.1mcp.app/guide/installation

This bash script outlines the steps to build the 1mcp-app agent from its source code. It includes cloning the repository, installing dependencies using pnpm, building the project, and finally running the agent with a specified configuration file.

```bash
# Clone repository
git clone https://github.com/1mcp-app/agent.git
cd agent

# Install dependencies
pnpm install

# Build
pnpm build

# Run
node build/index.js --config mcp.json
```

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

### Development Setup for 1MCP Agent Server (Bash)

Source: https://docs.1mcp.app/commands/serve

Shows development configurations for the 1MCP agent server, including enabling debug logging, setting health info levels, enabling async loading, and using a custom configuration directory with hot-reloading.

```bash
# Development with debug logging and full health info
npx -y @1mcp/agent serve \
  --log-level=debug \
  --health-info-level=full \
  --enable-async-loading

# Development with custom config directory
npx -y @1mcp/agent serve \
  --config-dir=./dev-config \
  --log-level=debug \
  --enable-config-reload
```

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

### 1MCP Registry Server Metadata (JSON)

Source: https://docs.1mcp.app/commands/registry

Example JSON structure representing the metadata for an MCP server in the 1MCP registry. This includes details like name, version, description, dependencies, platform compatibility, and installation instructions.

```json
{
  "name": "filesystem",
  "displayName": "File System Server",
  "description": "File system access and management capabilities",
  "version": "1.2.0",
  "category": "System",
  "tags": ["filesystem", "files", "local", "storage"],
  "maintainer": "Model Context Protocol Team",
  "license": "MIT",
  "homepage": "https://github.com/modelcontextprotocol/servers",
  "repository": "https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem",
  "documentation": "https://docs.modelcontextprotocol.io/servers/filesystem",
  "dependencies": [],
  "engines": {
    "node": ">=14.0.0"
  },
  "platforms": ["linux", "darwin", "win32"],
  "transport": ["stdio"],
  "capabilities": {
    "tools": ["read_file", "write_file", "list_directory", "create_directory"],
    "resources": ["file://*"]
  },
  "security": {
    "trusted": true,
    "sandboxed": false,
    "permissions": ["filesystem"]
  },
  "installation": {
    "npm": "@modelcontextprotocol/server-filesystem",
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem"]
  },
  "changelog": "https://github.com/modelcontextprotocol/servers/blob/main/CHANGELOG.md"
}
```

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

### Error Handling Examples (Bash)

Source: https://docs.1mcp.app/commands/preset/create

Illustrates common errors encountered during preset creation and their potential causes, such as invalid characters in names, incorrect filter syntax, or empty filters.

```bash
# Invalid characters in name
Error: Preset name can only contain letters, numbers, hyphens, and underscores

# Invalid filter syntax
Error: Invalid filter expression: unexpected token 'XYZ'

# Empty filter
Error: Filter expression cannot be empty
```

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

### Basic Preset Testing Examples (Bash)

Source: https://docs.1mcp.app/commands/preset/test

Demonstrates basic usage of the `preset test` command to test 'development' and 'production' presets. This helps verify that the presets correctly identify servers based on their tags and configuration.

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

# Test production preset
npx -y @1mcp/agent preset test production
```

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

### Development Workflow with Preset Commands (Bash)

Source: https://docs.1mcp.app/commands/preset/edit

This example outlines a typical development workflow using 1MCP agent commands. It includes steps for showing, editing, testing, and retrieving the URL for a preset, ensuring a smooth development and deployment process.

```bash
# 1. Review current preset
npx -y @1mcp/agent preset show development

# 2. Edit preset to add new servers
npx -y @1mcp/agent preset edit development

# 3. Test updated preset
npx -y @1mcp/agent preset test development

# 4. Get updated URL for clients
npx -y @1mcp/agent preset url development
```

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

### Configure STDIO Transport for MCP Server

Source: https://docs.1mcp.app/guide/essentials/server-management

Example of adding an MCP server using the STDIO transport type. This method is common for local MCP servers where 1MCP manages the server as a child process.

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

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

### Custom Server Configuration Example (Bash)

Source: https://docs.1mcp.app/commands/preset/url

Shows how the 'preset url' command adapts to a custom server configuration, reflecting the specified host and port in the generated URL.

```bash
# The URL will reflect your server's actual configuration
# For example, if running on port 3052:
npx -y @1mcp/agent preset url development
# Output: http://127.0.0.1:3052/?preset=development
```