Template Variables Reference

This page provides a complete reference for all variables available in custom instruction templates.

HTML Escaping Behavior

Important: 1MCP configures Handlebars with noEscape: true by default, which means all template variables output unescaped content. This is specifically designed for LLM instruction templates where HTML escaping would interfere with readability and AI parsing.

• All variables are unescaped: Use regular {{variable}} syntax for all content
• XML tags render cleanly: <server-name> outputs as <server-name> (not HTML entities)
• No triple braces needed: {{instructions}} outputs raw content directly

Server State Variables

{{serverCount}}

• Type: number
• Description: Number of connected servers that have instructions (LEGACY - kept for backward compatibility)
• Example: 3
• Notes: Only counts servers with non-empty instructions. Use instructionalServerCount for new templates.

{{instructionalServerCount}}

• Type: number
• Description: Number of connected servers that have instructions (clearer name for serverCount)
• Example: 3
• Notes: Only counts servers with non-empty instructions

{{connectedServerCount}}

• Type: number
• Description: Total number of connected servers (including those without instructions)
• Example: 5
• Notes: Counts all connected servers regardless of whether they have instructions

{{hasServers}}

• Type: boolean
• Description: Whether any servers with instructions are connected
• Example: true
• Usage: Primary conditional for template logic (same as hasInstructionalServers)

{{hasInstructionalServers}}

• Type: boolean
• Description: Whether any servers with instructions are connected
• Example: true
• Usage: Primary conditional for displaying instruction-based content

{{serverList}}

• Type: string
• Description: Newline-separated list of server names (alphabetical order)
• Example: "api-server\ndatabase-server\nweb-server"
• Usage: For simple text lists

{{serverNames}}

• Type: array<string>
• Description: Array of server names for iteration
• Example: ["api-server", "database-server", "web-server"]
• Usage: With {{#each}} helper for custom formatting

{{servers}}

• Type: array<ServerData>
• Description: Array of server objects for detailed iteration and conditional logic
• Structure:

  interface ServerData {
    name: string; // Server name (e.g., "api-server")
    instructions: string; // Server instructions content
    hasInstructions: boolean; // Whether this server has instructions
  }

• Usage: With {{#each}} for maximum template flexibility
• Example:

{{#each servers}}
{{#if hasInstructions}}
### {{name}} Server
<{{name}}>
{{instructions}}
</{{name}}>
{{/if}}
{{/each}}

{{pluralServers}}

• Type: string
• Description: Grammatically correct singular/plural form based on instructional server count
• Values: "server" (instructionalServerCount = 1) or "servers" (instructionalServerCount ≠ 1)
• Example: "servers"

{{isAre}}

• Type: string
• Description: Grammatically correct verb form based on instructional server count
• Values: "is" (instructionalServerCount = 1) or "are" (instructionalServerCount ≠ 1)
• Example: "are"

{{connectedPluralServers}}

• Type: string
• Description: Grammatically correct singular/plural form based on total connected server count
• Values: "server" (connectedServerCount = 1) or "servers" (connectedServerCount ≠ 1)
• Example: "servers"

{{connectedIsAre}}

• Type: string
• Description: Grammatically correct verb form based on total connected server count
• Values: "is" (connectedServerCount = 1) or "are" (connectedServerCount ≠ 1)
• Example: "are"

Content Variables

{{instructions}}

• Type: string (unescaped)

• Description: All server instructions wrapped in XML-like tags

• Format: <server-name>\nInstructions...\n</server-name>

• Usage: Use regular {{instructions}} syntax (unescaped by default)

• Example:

  <api-server>
  API server instructions for backend services
  </api-server>
  
  <web-server>
  Web server instructions for frontend development
  </web-server>

{{filterContext}}

• Type: string
• Description: Description of active filtering, or empty string if none
• Examples:
  • "" (no filtering)
  • " (filtered by tags: backend, api)"
  • " (filtered by advanced expression)"
  • " (filtered by preset)"

Configuration Variables

{{title}}

• Type: string
• Description: Title for the instruction template
• Default: "1MCP - Model Context Protocol Proxy"
• Customizable: Can be overridden in configuration
• Example: "My Custom MCP Gateway"

{{toolPattern}}

• Type: string
• Description: Tool naming pattern used by the proxy
• Default: "{server}_1mcp_{tool}"
• Customizable: Can be overridden in configuration
• Example: "{server}::{tool}"

{{examples}}

• Type: array<ToolExample>
• Description: Array of tool examples for documentation
• Structure:

  interface ToolExample {
    name: string; // Tool name with pattern applied
    description: string; // What the tool does
  }

Default Examples

Tool Name	Description
filesystem_1mcp_read_file	Read files through filesystem server
web_1mcp_search	Search the web through web server
database_1mcp_query	Query databases through database server

Custom Examples

You can provide custom examples in configuration:

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

Variable Usage Examples

Basic Substitution

Connected to {{connectedServerCount}} {{connectedPluralServers}}
With instructions: {{instructionalServerCount}} {{pluralServers}}

Output: Connected to 5 servers Output: With instructions: 3 servers

Conditional Content

{{#if hasServers}}
  {{instructionalServerCount}} {{pluralServers}} {{isAre}} providing instructions
  {{#if connectedServerCount}}
    ({{connectedServerCount}} total {{connectedPluralServers}} connected)
  {{/if}}
{{else}}
  No servers with instructions available
{{/if}}

Server Iteration (Simple)

{{#each serverNames}}
- Server: {{this}}
{{/each}}

Server Iteration (Detailed)

{{#each servers}}
{{#if hasInstructions}}
#### {{name}} Capabilities
<{{name}}>
{{instructions}}
</{{name}}>
{{/if}}
{{/each}}

Tool Examples

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

Complex Template

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

Variable Scope and Context

Filtering Impact

When filtering is active, variables reflect the filtered subset:

• {{connectedServerCount}} = count of all filtered servers
• {{instructionalServerCount}} = count of filtered servers with instructions
• {{serverNames}} = names of filtered servers only
• {{instructions}} = instructions from filtered servers only
• {{filterContext}} = description of active filter

Alphabetical Ordering

Server-related variables maintain consistent alphabetical ordering:

• {{serverList}} is alphabetically sorted
• {{serverNames}} array is alphabetically sorted
• {{instructions}} sections appear in alphabetical order

Real-time Updates

All variables reflect the current state:

• Server connections/disconnections update counts
• Instruction changes update content
• Filter changes update all relevant variables

Error Handling

Missing Variables

• Undefined variables render as empty strings
• Template engine continues processing
• No errors thrown for missing variables

Invalid Templates

• Syntax errors cause fallback to default template
• Errors are logged but don't crash the server
• Template compilation is cached for performance

Template Rendering

Note: 1MCP uses noEscape: true configuration, so all variables are unescaped by default:

• {{variable}} outputs raw content (unescaped)
• No need for triple braces - all content renders as-is
• Perfect for LLM consumption where XML tags and markup should be preserved
• XSS protection is not needed since templates are for LLM instruction purposes, not web display