Template Syntax Reference

Complete reference for Handlebars template syntax in 1MCP server templates.

Syntax Overview

1MCP server templates use Handlebars syntax with double curly braces for variable substitution:

{{variable}}           <!-- Variable access -->
{{namespace.variable}}  <!-- Nested variable access -->
{{helper arg1 arg2}}   <!-- Helper invocation -->

Variable Access

Standard Syntax

All template variables use double curly braces:

{{project.path}}
{{user.username}}
{{transport.client.name}}
{{project.custom.teamId}}

Nested Properties

Access nested properties using dot notation:

{{project.git.branch}}
{{project.custom.apiEndpoint}}
{{transport.client.version}}

Optional Values

Properties that may be undefined will render as empty strings:

{{project.git.branch}}    <!-- Renders empty if not in git repo -->
{{user.email}}            <!-- Renders empty if not set -->

Template Variables

Project Variables

Variable	Type	Description
project.path	string	Absolute path to current project
project.name	string	Project directory name
project.environment	string	Environment from .1mcprc or default
project.git.branch	string?	Current git branch
project.git.commit	string?	Current git commit hash
project.git.repository	string?	Git remote URL
project.custom.*	any	Custom values from .1mcprc

User Variables

Variable	Type	Description
user.username	string?	System username
user.name	string?	User's full name
user.email	string?	User email address
user.home	string?	Home directory path
user.uid	string?	User ID
user.gid	string?	Group ID
user.shell	string?	Default shell path

Transport Variables

Variable	Type	Description
transport.type	string	Transport type (http, sse, stdio)
transport.url	string?	Server URL (HTTP/SSE only)
transport.connectionId	string?	Connection identifier
transport.connectionTimestamp	string?	Connection time (ISO 8601)
transport.client.name	string	Client application name
transport.client.version	string	Client application version
transport.client.title	string?	Client display name

Conditional Expressions

If/Else

{{#if (eq project.environment 'production')}}
  production-value
{{else if (eq project.environment 'staging')}}
  staging-value
{{else}}
  development-value
{{/if}}

Unless

{{#unless (eq transport.client.name 'claude-code')}}
  This content is hidden for claude-code
{{/unless}}

Comparison Helpers

Equal (eq)

{{#if (eq project.environment 'production')}}
{{/if}}

Not Equal (ne)

{{#if (ne user.username 'root')}}
{{/if}}

Greater Than (gt)

{{#if (gt project.custom.count 5)}}
{{/if}}

Less Than (lt)

{{#if (lt project.custom.maxConnections 10)}}
{{/if}}

Logical Helpers

And

{{#if (and (eq project.environment 'production') (eq project.custom.region 'us'))}}
{{/if}}

Or

{{#if (or (eq project.custom.team 'backend') (eq project.custom.team 'devops'))}}
{{/if}}

Math Helpers

Basic Math

{{math value1 '+' value2}}     <!-- Addition -->
{{math value1 '-' value2}}     <!-- Subtraction -->
{{math value1 '*' value2}}     <!-- Multiplication -->
{{math value1 '/' value2}}     <!-- Division -->
{{math value1 '%' value2}}     <!-- Modulo -->
{{math value1 '**' value2}}    <!-- Exponentiation -->

Chained Operations

{{math value '*' 100 '/' total}}    <!-- (value * 100) / total, rounded -->

Specialized Math

{{subtract a b}}    <!-- a - b with null safety, returns 0 if undefined -->
{{div a b}}         <!-- a / b with zero safety, returns 0 if dividing by zero -->

String Helpers

Contains

{{#if (contains project.name 'admin')}}
  Contains 'admin'
{{/if}}

Starts With

{{#if (startsWith project.git.branch 'feature/')}}
  Feature branch
{{/if}}

Ends With

{{#if (endsWith project.name '-test')}}
  Test project
{{/if}}

Length

{{len project.name}}    <!-- String length -->

Substring

{{substring project.name 0 5}}    <!-- Characters 0-4 -->
{{substring project.name 3}}      <!-- From character 3 to end -->

Context Data Structure

TypeScript Interfaces

interface ContextData {
  project: {
    path: string;
    name: string;
    environment?: string;
    git?: {
      branch?: string;
      commit?: string;
      repository?: string;
    };
    custom?: Record<string, unknown>;
  };
  user: {
    username?: string;
    name?: string;
    email?: string;
    home?: string;
    uid?: string;
    gid?: string;
    shell?: string;
  };
  transport?: {
    type: string;
    url?: string;
    connectionId?: string;
    connectionTimestamp?: string;
    client?: {
      name: string;
      version: string;
      title?: string;
    };
  };
}

Template Rendering Process

1MCP processes templates through a five-step workflow:

Step 1: Context Collection

When a client connects, 1MCP collects context from:

• Current working directory (project path, name)
• Git repository (branch, commit, remote)
• .1mcprc file (custom context, environment)
• System information (user details)
• Connection details (transport, client info)

Step 2: Template Lookup

1MCP looks up templates from mcpTemplates in mcp.json that match the client's filter criteria (tags, preset).

Step 3: Variable Substitution

Each template configuration is rendered by substituting:

• {{variable}} placeholders with actual values
• {{#if}} conditionals are evaluated
• {{helper}} functions are executed

Step 4: Validation

validateOnReload is reserved for future use and currently has no effect.

Step 5: Server Creation

A server instance is created using the rendered configuration and connected to the client.

Caching

When cacheContext is enabled (default), rendered templates are cached by context hash to avoid reprocessing identical contexts.

Error Handling

Template Syntax Errors

If a template has invalid Handlebars syntax:

• strict mode: The affected template server is skipped; the error is logged. Other servers continue normally.
• graceful mode: Original template is used without rendering, error is logged

Missing Variables

Variables that don't exist in the context render as empty strings. This is expected behavior for optional values like {{project.git.branch}}.

Validation Errors

If the rendered configuration fails validation:

• strict mode: Template server is not created
• graceful mode: Original template configuration is used

Examples

Environment-Specific Configuration

{
  "mcpTemplates": {
    "adaptive-server": {
      "command": "node",
      "args": ["server.js"],
      "env": {
        "NODE_ENV": "{{project.environment}}",
        "LOG_LEVEL": "{{#if (eq project.environment 'production')}}warn{{else}}debug{{/if}}",
        "FEATURE_FLAG_X": "{{#if (gt project.custom.version 2)}}true{{else}}false{{/if}}"
      }
    }
  }
}

Client-Aware Configuration

{
  "mcpTemplates": {
    "client-specific": {
      "command": "npx",
      "args": ["-y", "my-server", "--client", "{{transport.client.name}}", "--version", "{{transport.client.version}}"],
      "disabled": "{{#if (or (eq transport.client.name 'cursor') (eq transport.client.name 'claude-code'))}}false{{else}}true{{/if}}"
    }
  }
}

Git-Aware Configuration

{
  "mcpTemplates": {
    "branch-aware": {
      "command": "npx",
      "args": ["-y", "context-server", "{{project.path}}", "--branch", "{{project.git.branch}}"],
      "disabled": "{{#if (startsWith project.git.branch 'hotfix/')}}true{{else}}false{{/if}}"
    }
  }
}

See Also

• MCP Server Templates Guide - Complete guide to using templates
• Handlebars Documentation - Official Handlebars reference
• Context Enrichment - Using .1mcprc files