preset url

Generate the client URL for a preset.

For a complete overview of preset management, see the Preset Commands Overview.

Synopsis

npx -y @1mcp/agent preset url <name>

Arguments

• <name>
  • The name of the preset to generate URL for.
  • Required: Yes

Description

The preset url command generates the client URL for a specific preset. This URL can be used directly in MCP client configurations to access the filtered server subset defined by the preset.

URL Format

http://host:port/mcp?preset=name

• host:port: Your 1MCP server address (default: 127.0.0.1:3050)
• preset=name: Query parameter that activates the preset

Examples

Basic Usage

# Generate URL for development preset
npx -y @1mcp/agent preset url development
# Output: http://127.0.0.1:3050/mcp?preset=development

# Generate URL for production preset
npx -y @1mcp/agent preset url production
# Output: http://127.0.0.1:3050/mcp?preset=production

Integration with Client Configuration

Claude Desktop

Use the stdio proxy to connect Claude Desktop to a running 1MCP HTTP server and apply the preset:

{
  "mcpServers": {
    "1mcp-development": {
      "command": "npx",
      "args": ["-y", "@1mcp/agent", "proxy", "--preset", "development"]
    }
  }
}

Cursor/VS Code

{
  "mcp.servers": {
    "1mcp-production": {
      "url": "http://127.0.0.1:3050/mcp?preset=production"
    }
  }
}

Use Cases

Development Environment Setup

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

Team Configuration Sharing

# Share preset URLs with team members
echo "Development: $(npx -y @1mcp/agent preset url team-dev)"
echo "Staging: $(npx -y @1mcp/agent preset url team-staging)"
echo "Production: $(npx -y @1mcp/agent preset url team-prod)"

Automation Scripts

#!/bin/bash
# Update client configurations with current preset URLs

DEV_URL=$(npx -y @1mcp/agent preset url development)
PROD_URL=$(npx -y @1mcp/agent preset url production)

# Update configuration files
sed -i "s|preset=development|${DEV_URL}|g" config/dev.json
sed -i "s|preset=production|${PROD_URL}|g" config/prod.json

Dynamic Server Selection

When a client uses a preset URL:

1. Request Processing: 1MCP server receives request with ?preset=name
2. Preset Resolution: Server looks up the preset configuration
3. Server Filtering: Applies preset's tag query to available servers
4. Dynamic Response: Returns only matching servers to the client
5. Unknown preset: Returns HTTP 400; it never falls back to an unfiltered server list

Context Switching

Clients can switch server contexts by changing the preset parameter:

# Development context
http://127.0.0.1:3050/mcp?preset=development

# Production context
http://127.0.0.1:3050/mcp?preset=production

# All servers (no filtering)
http://127.0.0.1:3050/mcp

Error Handling

Preset Not Found

npx -y @1mcp/agent preset url nonexistent
# Error: Preset 'nonexistent' not found

Server Configuration Issues

If there are issues with the server configuration, the URL is still generated but may not work as expected. Use preset test <name> to validate server matching.

URL Validation

The generated URLs are validated to ensure:

• Preset exists: The named preset is in your configuration
• Valid format: URL follows proper HTTP format
• Server accessibility: Based on current server configuration

Workflow Integration

Common usage patterns:

# 1. Create or verify preset exists
npx -y @1mcp/agent preset list

# 2. Generate URL for client configuration
npx -y @1mcp/agent preset url development

# 3. Test preset to verify server matching
npx -y @1mcp/agent preset test development

# 4. Configure your MCP client with the generated URL

Advanced Usage

Custom Server Configuration

If your 1MCP server runs on a different host/port:

# 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/mcp?preset=development

Multiple Environments

# Generate URLs for different environments
for env in development staging production; do
  echo "$env: $(npx -y @1mcp/agent preset url $env)"
done

See Also

• preset show - Show complete preset details including URL
• preset test - Test preset server matching
• preset create - Create new presets for URL generation
• preset list - List all available presets