Custom Instruction Templates

1MCP allows you to customize the instruction templates that are sent to LLM clients. This enables you to brand your proxy, provide custom documentation, or tailor the educational content to your specific use case.

Overview

By default, 1MCP generates educational instruction templates that help LLMs understand how to use the proxy effectively. You can override this with your own Handlebars template that includes:

• Custom branding and messaging
• Specific instructions for your use case
• Variable substitution with real-time server data
• Conditional content based on connected servers

Manage Templates in the Admin Console

Open Admin Console > Instructions to manage named instruction templates without editing the configuration file directly. Each template contains two independent variants:

• Initialization is returned to a new MCP client during initialization.
• CLI is rendered by 1mcp instructions and the corresponding HTTP endpoint.

The built-in default template always provides both variants. It is protected: you cannot edit or delete it, but you can clone it as the starting point for a managed template.

The editor supports this workflow:

1. Create or clone a template and edit either variant.
2. Save the draft. Drafts may be saved even when one variant contains invalid Handlebars, so unfinished work is not lost.
3. Validate both variants and preview them against an explicit server context.
4. Activate the template. Activation succeeds only when both variants are valid.

Exactly one template is active per Runtime Scope. Presets, tags, and clients do not select the active template. An active template cannot be deleted; activate another template first. The Admin Console also shows a delete preview before it applies a deletion.

Preview Context and Filters

Preview uses an explicit, ephemeral context. Choose the servers and the same preset, tags, or advanced tag filter that the target client will use. The preview applies that filter before building variables such as {{servers}}, {{serverNames}}, and {{filterContext}}. It does not create a persistent client session or change the active template.

Preview both variants when a change affects shared variables. The initialization and CLI variants may intentionally produce different structures from the same filtered server data.

Runtime Behavior and Fallback

Activating a template updates configuration for future rendering. Existing initialized MCP sessions keep the instructions they already received; new MCP connections and subsequent 1mcp instructions calls use the active selection.

If the active variant fails during rendering, 1MCP renders the built-in variant for that surface and records a structured Admin error. The active selection is preserved so operators can inspect and repair the template. A failure in cli does not replace a valid initialization variant, and vice versa.

Managed Configuration

The Admin Console stores managed templates in mcp.json:

{
  "instructionTemplates": {
    "team": {
      "initialization": "# {{title}}\n\n{{instructions}}",
      "cli": "Use `1mcp inspect <server>` before `1mcp run`.\n\n{{instructions}}"
    }
  },
  "activeInstructionTemplate": "team"
}

Admin-managed publication state

publishedInstructionTemplates is an optional internal snapshot maintained by the Admin workflow. It preserves the last activated output when an active template is saved as an invalid draft and across restarts. Do not edit this field by hand; edit instructionTemplates drafts and use Activate to publish validated variants.

Do not add a default entry to instructionTemplates; that identity is reserved for the built-in template. activeInstructionTemplate must be default or the identity of a configured managed template.

When activeInstructionTemplate is present, the managed selection takes precedence for both surfaces. When it is absent, initialization keeps the legacy file or --instructions-template behavior described below, while CLI output uses the built-in CLI template.

Migrate a Legacy Template

Use Import legacy template in the Admin Console to copy the currently configured legacy initialization template into a named draft. Import does not overwrite the legacy file and does not activate the draft. The new template receives:

• the legacy content as its initialization variant;
• the built-in content as its cli variant.

Review and validate both variants, preview the intended filter context, and then activate the managed template. Once a managed selection is active, it takes precedence over the legacy initialization template. Keep the legacy file until new connections and CLI output have been verified, then remove the old serve option or file when convenient.

Template Variables

Your custom templates have access to the following variables:

Server State Variables

Variable	Type	Description	Example
{{serverCount}}	number	Number of connected servers with instructions	3
{{hasServers}}	boolean	Whether any servers are connected	true
{{serverList}}	string	Newline-separated list of server names	"api-server\nweb-server"
{{serverNames}}	array	Array of server names for iteration	["api-server", "web-server"]
{{servers}}	array	Array of server objects for detailed iteration (includes all servers)	[{name: "api-server", instructions: "...", hasInstructions: true}, {name: "no-docs", instructions: "", hasInstructions: false}]
{{pluralServers}}	string	"server" or "servers" based on count	"servers"
{{isAre}}	string	"is" or "are" based on count	"are"

Server Objects ({{servers}} array)

Each server object in the {{servers}} array contains:

Property	Type	Description
name	string	Server name (e.g., "api-server")
instructions	string	Server's instruction content (empty string if no instructions)
hasInstructions	boolean	Whether this server has instructions

Note: All connected servers are included in the array, even if they have no instructions. Servers without instructions will have hasInstructions: false and an empty string for instructions.

Important: The serverCount and related variables (serverList, serverNames) only include servers that have instructions, while the servers array includes all connected servers regardless of whether they have instructions.

Content Variables

Variable	Type	Description
{{instructions}}	string	All server instructions wrapped in XML-like tags (unescaped output)
{{filterContext}}	string	Filter description or empty string

XML-Style Server Instructions

Server instructions are wrapped in XML-like tags to clearly identify their source and scope:

<server-name>
Server instructions content here
</server-name>

This format helps LLMs understand which instructions come from which server and maintain clear boundaries between different server capabilities.

Configuration Variables

Variable	Type	Description	Default
{{title}}	string	Title for the template	"1MCP - Model Context Protocol Proxy"
{{toolPattern}}	string	Tool naming pattern	"{server}_1mcp_{tool}"
{{examples}}	array	Array of tool examples	See examples reference

Using Custom Templates

Command Line Option

Use the --instructions-template option with the serve command:

# Use a specific template file
1mcp serve --instructions-template ./my-template.md

# Use default template in config directory
1mcp serve  # Looks for instructions-template.md in config dir

Template File Location

By default, 1MCP looks for instructions-template.md in your config directory:

• macOS/Linux: ~/.config/1mcp/instructions-template.md
• Windows: %APPDATA%/1mcp/instructions-template.md

You can also specify a custom path using the CLI option.

Move to Managed Configuration

For a supported configuration workflow, import the legacy file into a managed template as described above. To replace or suppress instructions from one configured server, use a server instruction override instead of adding per-client template settings.

Template Syntax

1MCP uses Handlebars as the template engine, which provides:

• Variable substitution: {{variable}}
• Conditional content: {{#if condition}}...{{/if}}
• Loops: {{#each array}}...{{/each}}
• Helpers: Built-in logical and comparison operators

HTML Escaping Behavior

Important: 1MCP configures Handlebars with noEscape: true by default, which means:

• All variables are unescaped: {{instructions}} outputs raw content without HTML entity escaping
• XML tags render cleanly: <server-name> stays as <server-name> (not <server-name>)
• No triple braces needed: Use regular {{variable}} syntax for all content
• Ready for LLM consumption: Output is clean and readable for AI processing

This configuration is specifically designed for LLM instruction templates where HTML escaping would make the content less readable and harder for AI models to parse.

Basic Template Example

# {{title}}

{{#if hasServers}}
You have {{serverCount}} {{pluralServers}} connected:

{{#each serverNames}}

- ✅ {{this}}
  {{/each}}

## Server Instructions

The following sections contain instructions from each connected MCP server. Each server's instructions are wrapped in XML-like tags to clearly identify their source and scope.

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

{{/if}}
{{/each}}

## Tool Usage

Tools follow the pattern: `{{toolPattern}}`
{{else}}
⏳ No servers are currently connected.
{{/if}}

Advanced Template Example

# {{title}}

{{#if hasServers}}
You are interacting with 1MCP, a proxy server that aggregates capabilities from multiple MCP (Model Context Protocol) servers. 1MCP acts as a unified gateway, allowing you to access tools and resources from various specialized MCP servers through a single connection.

## How 1MCP Works

- **Unified Access**: Connect to multiple MCP servers through one proxy
- **Tool Aggregation**: All tools are available with the naming pattern \`{{toolPattern}}\`
- **Resource Sharing**: Access files, data, and capabilities across different servers
- **Intelligent Routing**: Your requests are automatically routed to the appropriate servers

## Currently Connected Servers

{{serverCount}} MCP {{pluralServers}} {{isAre}} currently available{{filterContext}}:

{{serverList}}

## Available Capabilities

All tools from connected servers are accessible using the format: \`{{toolPattern}}\`

Examples:
{{#each examples}}

- \`{{name}}\` - {{description}}
  {{/each}}

## Server-Specific Instructions

The following sections contain instructions from each connected MCP server. Each server's instructions are wrapped in XML-like tags (e.g., \`<server-name>instructions</server-name>\`) to clearly identify their source and scope.

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

{{/if}}
{{/each}}

## Tips for Using 1MCP

- Tools are namespaced by server to avoid conflicts

{{else}}
You are interacting with 1MCP, a proxy server that aggregates capabilities from multiple MCP (Model Context Protocol) servers.

## Current Status

No MCP servers are currently connected. 1MCP is ready to connect to servers and provide unified access to their capabilities once they become available.

## What 1MCP Provides

- **Unified Access**: Connect to multiple MCP servers through one proxy
- **Tool Aggregation**: Access tools using the pattern \`{{toolPattern}}\`
- **Resource Sharing**: Share files, data, and capabilities across servers
- **Intelligent Routing**: Automatic request routing to appropriate servers

1MCP will automatically detect and connect to available MCP servers. Once connected, their tools and capabilities will become available through the unified interface.
{{/if}}`

Template Best Practices

1. Use Conditional Content

Always check if servers are available before showing server-specific content:

{{#if hasServers}}
  <!-- Server-specific content -->
{{else}}
  <!-- No servers message -->
{{/if}}

2. Handle Pluralization

Use the provided helper variables for proper grammar:

{{serverCount}} {{pluralServers}} {{isAre}} available

3. All Variables are Unescaped

Since 1MCP uses noEscape: true, all variables output raw content without HTML escaping:

{{instructions}}    <!-- Outputs raw content (unescaped) -->
{{name}}           <!-- Outputs server name as-is -->
{{title}}          <!-- All variables render without escaping -->

This means XML tags like <server-name> will render cleanly in the output, making it perfect for LLM consumption.

4. Provide Context

Include information about filtering when active:

{{serverCount}} servers available{{filterContext}}

5. Use Individual Server Iteration

For maximum flexibility, iterate over individual servers instead of using the concatenated instructions:

{{#each servers}}
{{#if hasInstructions}}
### {{name}} Capabilities
<{{name}}>
{{instructions}}
</{{name}}>
{{else}}
### {{name}}
This server is connected but has no instructions available.
{{/if}}
{{/each}}

This gives you control over per-server formatting, conditional inclusion, and custom logic. You can handle servers with and without instructions differently.

6. Explain XML Tag Format

Help LLMs understand the XML tag structure by providing context:

## Server Instructions

Each server's instructions are wrapped in XML-like tags (e.g., `<server-name>content</server-name>`) to clearly identify their source and scope.

7. Make It Helpful

Include examples and usage tips to help LLMs understand your specific setup:

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

Error Handling

If your custom template has syntax errors or fails to render:

1. Fallback: 1MCP automatically falls back to the default template
2. Logging: Errors are logged for debugging
3. Validation: Template compilation errors are caught and reported

Testing Templates

You can test your templates by:

1. Starting the server: Use your template and check the logs
2. Connecting a client: Verify the instructions are rendered correctly
3. Using different filters: Test with various server combinations
4. Checking edge cases: Test with no servers, single server, etc.

Server Instruction Overrides

Custom templates allow you to override, filter, or customize server instructions using Handlebars logic. This gives you complete control over how server instructions are presented to the LLM.

For detailed guidance on server instruction overrides including patterns, techniques, and examples, see the dedicated Server Instruction Overrides guide.

Example Templates

See the Template Examples page for complete template examples for different use cases.