How to Configure MCP Servers with Context-Saving Mode and @-Mention Activation in Claudian

Claudian's context-saving mode hides MCP server tools by default and activates them only when you @-mention the server name in your prompt, reducing token usage and preventing accidental tool calls.

The YishenTu/claudian plugin for Obsidian supports the Model Context Protocol (MCP), allowing you to extend Claude's capabilities with external tools. When you configure MCP servers with context-saving mode enabled, you gain granular control over which tools are exposed to the model during each conversation. This guide explains the exact implementation details from the source code to help you set up context-saving mode and activate servers using @-mentions.

Understanding Context-Saving Mode

Context-saving mode determines whether an MCP server's tools are immediately available to Claude or hidden until explicitly requested. According to the ClaudianMcpServer interface defined in src/core/types/mcp.ts, each server configuration includes an enabled flag and a contextSaving flag.

The behavior falls into three distinct states:

• Enabled + contextSaving: true – The server is inactive unless the prompt contains @<serverName>. Tools are hidden from the model to save context window space.
• Enabled + contextSaving: false – The server is always active regardless of mentions. Tools are available in every conversation.
• Disabled – The server is ignored completely and cannot be activated via mentions.

The default configuration in DEFAULT_MCP_SERVER sets contextSaving: true for all new servers, meaning tools are hidden by default until you explicitly invoke them.

Configuring MCP Servers in .claudian-mcp.json

You configure servers by adding entries to your MCP configuration file, typically located at .claudian-mcp.json in your vault root or managed through the settings UI. The configuration uses a standard mcpServers block for connection details and a _claudian block for Claudian-specific metadata including the context-saving flag.

Here is an example configuration showing both active and context-saving modes:

{
  "mcpServers": {
    "my-local": { "command": "my-tool", "args": ["--foo"] },
    "remote-api": { "type": "http", "url": "https://api.example.com/claude" }
  },
  "_claudian": {
    "servers": {
      "my-local": {
        "enabled": true,
        "contextSaving": true,
        "description": "Local helper that should be invoked only on demand"
      },
      "remote-api": {
        "enabled": true,
        "contextSaving": false,
        "description": "Always-on remote toolset"
      }
    }
  }
}

In this configuration, my-local operates in context-saving mode and requires an @-mention to activate, while remote-api remains constantly available. The McpStorage class in src/core/storage/McpStorage.ts persists these settings and respects the default values defined in src/core/types/mcp.ts.

How @-Mention Activation Works

When you submit a prompt containing @serverName, the McpServerManager class orchestrates the activation flow. The process involves three key operations defined in src/core/mcp/McpServerManager.ts and src/utils/mcp.ts.

First, the manager extracts mentions using the extractMentions(prompt) method, which internally calls extractMcpMentions from src/utils/mcp.ts. This utility uses the regex @([a-zA-Z0-9._-]+) to identify valid server names in your text.

Second, the transformMentions(prompt) method converts each detected mention into the format @<name> MCP, which signals the Claude SDK that the server should be active for this specific request.

Third, getActiveServers(mentions) filters the full server list to return only configurations that are either (a) not in context-saving mode, or (b) explicitly mentioned in the current prompt.

Here is how the activation flow looks in practice:

// Inside the conversation controller
const manager = this.plugin.mcpManager;          // instance of McpServerManager
const mentions = manager.extractMentions(prompt); // → Set { "my-local" }
const transformed = manager.transformMentions(prompt);
// transformed === "Please list the files and then run @my-local MCP to format them."
const activeServers = manager.getActiveServers(mentions);
// activeServers contains only the config for "my-local"

Managing Tool Visibility on Context-Saving Servers

Even when a context-saving server is activated via @-mention, you can still exclude specific tools from being available. The McpServerManager maintains a disallowedTools list that is dynamically built based on your configuration.

When you disable a tool through the settings UI using McpSettingsManager.updateDisabledTool(), the manager adds it to the exclusion list. For context-saving servers, this exclusion only applies when the server is actually mentioned in the prompt. If the server is not active, its disabled tools are irrelevant since no tools from that server are exposed.

await manager.updateDisabledTool(server, 'myTool', false); // disables "myTool"

The getDisallowedMcpTools and collectDisallowedTools methods in McpServerManager.ts handle this logic, ensuring that disabled tools are properly filtered from the SDK options passed to ConversationController.ts.

Adding Servers via the Settings UI

You can configure servers without manually editing JSON by using the built-in settings interface. The McpSettingsManager class in src/features/settings/ui/McpSettingsManager.ts renders the configuration UI, including a small "@" badge next to context-saving servers with a tooltip explaining the activation rule.

To add a new server programmatically or through the UI modal:

// Open modal from the settings pane
new McpServerModal(app, plugin, null, async (saved) => {
  await manager.saveServer(saved, null); // saves and reloads all views
}, 'stdio'); // pre-select stdio type

The McpServerModal automatically pre-fills the contextSaving flag from DEFAULT_MCP_SERVER (defaulting to true) as implemented in lines 47-48 of src/features/settings/ui/McpServerModal.ts.

Summary

• Context-saving mode hides MCP server tools by default to preserve context window space and prevent unintended tool usage.
• @-mention activation requires typing @serverName in your prompt, which McpServerManager detects using the regex @([a-zA-Z0-9._-]+) and transforms to @serverName MCP for the SDK.
• Configuration happens via .claudian-mcp.json using the _claudian.servers block with contextSaving: true, or through the settings UI where new servers default to context-saving mode.
• Tool filtering works alongside context-saving mode through the disallowedTools array, which is only enforced when the server is actively mentioned.
• Key implementation files include src/core/types/mcp.ts for type definitions, src/core/mcp/McpServerManager.ts for activation logic, and src/utils/mcp.ts for mention extraction utilities.

Frequently Asked Questions

What is the default context-saving setting for new MCP servers in Claudian?

New servers default to contextSaving: true according to the DEFAULT_MCP_SERVER constant defined in src/core/types/mcp.ts. This means tools are hidden by default and require @-mention activation unless you explicitly disable context-saving mode in the server configuration.

How does Claudian detect @-mentions in prompts?

The detection uses the extractMcpMentions utility in src/utils/mcp.ts, which applies the regex @([a-zA-Z0-9._-]+) to scan user prompts for server names. Only mentions corresponding to enabled servers with contextSaving: true are considered valid activators.

Can I disable specific tools on a context-saving server?

Yes. Use McpSettingsManager.updateDisabledTool() or the settings UI to disable individual tools. These tools are added to disallowedTools via McpServerManager.getDisallowedMcpTools() and are excluded from the SDK request only when the server is activated via @-mention.

What happens if I @-mention a disabled MCP server?

If a server is marked as enabled: false in the configuration, the McpServerManager ignores it completely during the getActiveServers() filtering phase. Even if you include @serverName in your prompt, disabled servers cannot be activated and their tools remain unavailable.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}