How MCP Servers Integrate with @mcp-server Mention Activation in Claudian

Claudian implements @mcp-server mention activation by parsing @mentions in user prompts, transforming them into SDK-compatible "@name MCP" tokens, and passing server names through queryOptions to selectively enable tool namespaces only when explicitly referenced.

Claudian is an open-source interface for Claude that supports MCP (Model Context Protocol) servers to extend functionality with external tools. The repository implements a sophisticated mention-based activation system where MCP servers remain hidden from the model context until the user explicitly @mentions the server name in their prompt. This article examines the complete integration flow from UI dropdown selection to SDK request preparation, based on the actual implementation in the YishenTu/claudian codebase.

Architecture of @mcp-server Mention Activation

The integration spans multiple layers of the application, from type definitions to UI components and request orchestration.

MCP Configuration and Context-Saving Mode

In src/core/types/mcp.ts, the ClaudianMcpServer interface defines the configuration structure for each server, including the critical contextSaving boolean flag. When contextSaving is set to true, the server's tools are hidden from the model unless the user explicitly mentions the server name in their prompt.

The configuration also includes enabled, disabledTools, and description fields that control server availability and tool filtering. Servers defined in the user-editable mcp.json file are loaded by the McpServerManager at runtime.

Mention Extraction and Transformation Utilities

The low-level text processing resides in src/utils/mcp.ts. The extractMcpMentions function uses a regex pattern to identify valid server names preceded by the @ symbol:

// src/utils/mcp.ts
export function extractMcpMentions(text: string, validNames: Set<string>): Set<string> {
  const mentions = new Set<string>();
  const regex = /@([a-zA-Z0-9._-]+)(?!\/)/g;
  let match: RegExpExecArray | null;

  while ((match = regex.exec(text)) !== null) {
    const name = match[1];
    if (validNames.has(name)) {
      mentions.add(name);
    }
  }
  return mentions;
}

The transformMcpMentions function rewrites valid mentions to include the required " MCP" suffix that the Claude SDK expects:

// src/utils/mcp.ts
export function transformMcpMentions(text: string, validNames: Set<string>): string {
  if (validNames.size === 0) return text;
  const sortedNames = Array.from(validNames).sort((a, b) => b.length - a.length);
  const escapedNames = sortedNames.map(escapeRegExp).join('|');
  const pattern = new RegExp(
    `@(${escapedNames})(?! MCP)(?!/)(?![a-zA-Z0-9_-])(?!\\.[a-zA-Z0-9_-])`,
    'g'
  );
  return text.replace(pattern, '@$1 MCP');
}

Server Management Layer

src/core/mcp/McpServerManager.ts wraps the utility functions and provides the public API used by other components. It exposes extractMentions(text) which calls extractMcpMentions with the set of context-saving server names, and transformMentions(text) which invokes transformMcpMentions. The manager also provides getContextSavingServers() to supply the UI with the list of mentionable servers.

UI Dropdown Integration

When a user types the @ character in the chat input, src/shared/mention/MentionDropdownController.ts triggers and queries the available MCP servers. It calls this.mcpManager.getContextSavingServers() to retrieve servers eligible for mention activation, then adds items of type mcp-server to the dropdown completion list.

Request Pipeline Integration

The src/features/chat/controllers/InputController.ts orchestrates the final message preparation. Before sending to the Claude SDK, it performs three critical operations:

1. Extracts mentions using plugin.mcpManager.extractMentions(promptToSend)
2. Transforms the prompt text using plugin.mcpManager.transformMentions(promptToSend)
3. Constructs the queryOptions object including mcpMentions and enabledMcpServers

// src/features/chat/controllers/InputController.ts (excerpt)
if (mcpMentions.size > 0 || (enabledMcpServers && enabledMcpServers.size > 0)) {
  queryOptions = {
    ...queryOptions,
    mcpMentions,
    enabledMcpServers,
  };
}

The Complete Activation Flow

When a user activates an MCP server via @mention, the system processes the request through the following pipeline:

1. Dropdown Population – The MentionDropdownController lists only servers with contextSaving: true retrieved from McpServerManager.getContextSavingServers().

2. Text Insertion – Upon selection, the UI inserts @server-name into the editor buffer.

3. Mention Extraction – InputController.sendMessage calls extractMentions() which scans the full prompt for @tokens matching valid context-saving server names.

4. SDK Transformation – The transformMentions() method rewrites each valid @name to @name MCP (required by the backend to distinguish MCP references from plain text).

5. Option Packaging – The controller packs the extracted names into queryOptions.mcpMentions as a Set<string>, alongside enabledMcpServers containing globally enabled servers.

6. Tool Namespace Activation – The Claude SDK receives the options and enables the tool namespace mcp__server-name__<tool> only for the mentioned servers, applying any per-server disabledTools filters.

Code Examples

Configuring a Context-Saving MCP Server

Define servers in your mcp.json configuration file:

{
  "mcpServers": {
    "my-mcp-server": {
      "type": "http",
      "url": "http://localhost:8000"
    }
  },
  "_claudian": {
    "servers": {
      "my-mcp-server": {
        "enabled": true,
        "contextSaving": true,
        "disabledTools": ["my_tool_to_hide"],
        "description": "Local test server"
      }
    }
  }
}

Using @mentions in Prompts

Users activate servers by mentioning them in the chat input:

Please search the database for recent entries.
@my-mcp-server

Behind the scenes, InputController processes this text:

// src/features/chat/controllers/InputController.ts
const mcpMentions = plugin.mcpManager.extractMentions(promptToSend);
promptToSend = plugin.mcpManager.transformMentions(promptToSend);

Summary

• Context-saving mode hides MCP server tools from the model unless explicitly @mentioned, reducing prompt noise and unnecessary tool registration.
• Dual-phase processing separates mention extraction (identifying valid servers) from transformation (adding the " MCP" suffix required by the SDK).
• Manager pattern centralizes server logic in McpServerManager.ts, providing clean APIs for both UI components and request controllers.
• SDK integration passes mention data through queryOptions.mcpMentions, allowing the Claude backend to selectively enable tool namespaces only for referenced servers.

Frequently Asked Questions

What is the purpose of the " MCP" suffix in @mcp-server mentions?

The " MCP" suffix is required by the Claude SDK to distinguish MCP server references from regular text or other mention types. The transformMcpMentions function in src/utils/mcp.ts appends this suffix only when preparing the API request, while the UI continues to display the clean @name format for better readability.

How does Claudian determine which MCP servers appear in the @mention dropdown?

The MentionDropdownController calls mcpManager.getContextSavingServers() to retrieve only servers with contextSaving: true set in their configuration. Servers without this flag are either always enabled (if enabled: true) or completely disabled, and thus do not appear in the mention completion list.

What is the difference between context-saving mode and globally enabled MCP servers?

Context-saving servers (contextSaving: true) require explicit @mention activation and their tools are hidden from the model context otherwise. Globally enabled servers appear in enabledMcpServers and remain active for all requests regardless of mentions. The InputController passes both sets to the SDK via separate queryOptions properties.

Where does the actual tool filtering occur when a server is mentioned?

The final tool namespace activation occurs within the internal Claude SDK when it receives the queryOptions object containing mcpMentions and enabledMcpServers. The SDK enables the specific mcp__server-name__<tool> namespace only for mentioned servers, while applying any disabledTools filters defined in the server configuration.

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