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

> Learn how MCP servers integrate with @mcp-server mention activation in Claudian. Claudian parses mentions, transforms them into tokens, and enables tool namespaces for selective integration.

- Repository: [YishenTu/claudian](https://github.com/YishenTu/claudian)
- Tags: how-to-guide
- Published: 2026-03-17

---

**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`](https://github.com/YishenTu/claudian/blob/main/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`](https://github.com/YishenTu/claudian/blob/main/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`](https://github.com/YishenTu/claudian/blob/main/src/utils/mcp.ts). The `extractMcpMentions` function uses a regex pattern to identify valid server names preceded by the @ symbol:

```typescript
// 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:

```typescript
// 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`](https://github.com/YishenTu/claudian/blob/main/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`](https://github.com/YishenTu/claudian/blob/main/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`](https://github.com/YishenTu/claudian/blob/main/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`

```typescript
// 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`](https://github.com/YishenTu/claudian/blob/main/mcp.json) configuration file:

```json
{
  "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:

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

```

Behind the scenes, `InputController` processes this text:

```typescript
// 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`](https://github.com/YishenTu/claudian/blob/main/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`](https://github.com/YishenTu/claudian/blob/main/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.