# How to Use the @‑Mention Dropdown for Files, Agents, and MCP Servers in Claudian

> Master the Claudian @-mention dropdown to effortlessly insert files, agents, and MCP servers into your chat prompts. Improve your workflow today.

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

---

**The @‑mention dropdown in Claudian provides a context‑aware picker that lets you insert vault files, external folders, AI agents, and MCP servers directly into chat prompts by typing `@` followed by a search query.**

The @‑mention dropdown is the central UI component in the Claudian Obsidian plugin that streamlines prompt construction by offering searchable access to your vault contents, external directories, specialized agents, and Model‑Context‑Protocol (MCP) servers. According to the YishenTu/claudian source code, the system is implemented in TypeScript within [`src/shared/mention/MentionDropdownController.ts`](https://github.com/YishenTu/claudian/blob/main/src/shared/mention/MentionDropdownController.ts) and exposes a controller‑based API that developers can wire into custom chat views.

## Triggering the Dropdown Detection

The dropdown appears automatically when the editor detects a leading `@` that is either at the start of the line or preceded by whitespace. In [`src/shared/mention/MentionDropdownController.ts`](https://github.com/YishenTu/claudian/blob/main/src/shared/mention/MentionDropdownController.ts), the `handleInputChange` method (lines 31‑64) runs a 200 ms debounce to extract the text before the cursor and determine whether to invoke the picker. This ensures the UI remains responsive while you type without triggering redundant searches.

## Searching Vault Files, Agents, and MCP Servers

Once triggered, the `showMentionDropdown` method (lines 200‑340) filters four distinct categories based on the text following the `@` symbol:

- **Vault files and folders** – Cached via callback getters like `getCachedVaultFiles` and `getCachedVaultFolders`
- **External‑context files** – Scanned dynamically by `externalContextScanner` from user‑defined external paths
- **Agents** – Provided by the `AgentMentionProvider` interface (typically implemented by `AgentService`)
- **MCP servers** – Provided by the `McpMentionProvider` interface (typically implemented by `McpServerManager`)

Each category is rendered as a selectable list item, with icons indicating whether the entry is a file, folder, agent, or server.

## Special Filter Modes and Shortcuts

### The `agents/` Shortcut

Typing `@agents/` forces the dropdown into **agent‑filter mode**, displaying only agents that match the remainder of your query. This logic resides in the `isFilterSearch && searchLower.startsWith('agents/')` branch of `showMentionDropdown` (lines 12‑22). When active, the controller bypasses file and MCP listings to show agent names exclusively, making it efficient to invoke specialized AI personas without scrolling through unrelated results.

### Context‑Saving MCP Mentions

When an MCP server has *context‑saving* enabled, the dropdown adds a special “@‑server” badge. The controller extracts MCP mentions from the entire prompt text using `extractMcpMentions` (see `updateMcpMentionsFromText` in lines 15‑28). The resulting set is stored via the `setMentionedMcpServers` callback and can trigger UI updates in the chat toolbar, allowing the system to persist which servers are active across conversation turns.

## Initializing the Dropdown Controller

To embed the @‑mention system in a custom chat view, instantiate `MentionDropdownController` with a container element, input element, and a callbacks bundle that bridges the UI to your application state.

```typescript
import { MentionDropdownController } from '@/shared/mention/MentionDropdownController';
import { McpServerManager } from '@/core/mcp/McpServerManager';
import { AgentService } from '@/core/agents/AgentService';

const callbacks = {
  onAttachFile: (path) => editor.replaceSelection(`[[${path}]]`),
  onMcpMentionChange: (servers) => mcpToolbar.addMentionedServers(servers),
  getMentionedMcpServers: () => mcpToolbar.getEnabledServers(),
  setMentionedMcpServers: (set) => mcpToolbar.setEnabledServers(Array.from(set)),
  addMentionedMcpServer: (name) => mcpToolbar.addEnabledServer(name),
  getExternalContexts: () => settings.getExternalContextPaths(),
  getCachedVaultFolders: () => vault.getFolders(),
  getCachedVaultFiles: () => vault.getFiles(),
  normalizePathForVault: (p) => p ? normalizePath(p) : null,
};

const dropdown = new MentionDropdownController(
  containerEl,
  inputEl,
  callbacks,
  { fixed: false }
);

// Wire the required provider services
dropdown.setMcpManager(mcpServerManager as unknown as McpMentionProvider);
dropdown.setAgentService(agentService as unknown as AgentMentionProvider);

// Bind input events
inputEl.addEventListener('input', () => dropdown.handleInputChange());
inputEl.addEventListener('keydown', (e) => dropdown.handleKeydown(e));

```

Key integration points include `setMcpManager` and `setAgentService` (lines 74‑81), which inject the respective provider implementations used for the `agents/` filter and MCP server listing.

## Programmatic MCP Server Management

While the dropdown handles `@` mentions, the toolbar component in [`src/features/chat/ui/InputToolbar.ts`](https://github.com/YishenTu/claudian/blob/main/src/features/chat/ui/InputToolbar.ts) (lines 14‑45) provides a wrench icon for toggling servers manually. Clicking the badge calls internal toggle methods (lines 86‑110) that update the visual state and fire the `onChange` callback. You can also manipulate this state programmatically:

```typescript
// Enable specific servers via code
mcpToolbar.setEnabledServers(['server-a', 'server-b']);

// Clear all enabled servers
mcpToolbar.clearEnabled();

```

When a user selects an MCP server via the `@` mention dropdown, the controller extracts the server name using logic from [`src/utils/mcp.ts`](https://github.com/YishenTu/claudian/blob/main/src/utils/mcp.ts), updates the stored set via `setMentionedMcpServers`, and the toolbar badge automatically highlights the server and displays a count for multiple active instances.

## Summary

- **Triggering**: Type `@` at the start of a line or after whitespace to invoke the dropdown via `handleInputChange` (lines 31‑64).
- **Search scope**: The dropdown queries vault files, external contexts, agents, and MCP servers through the `showMentionDropdown` filter logic (lines 200‑340).
- **Agent filtering**: Use the `@agents/` prefix to restrict results to AI agents only (lines 12‑22).
- **MCP context**: Context‑saving servers are tracked via `extractMcpMentions` and synchronized through the `setMentionedMcpServers` callback.
- **Integration**: Wire the controller with `setMcpManager` and `setAgentService`, then bind input and keyboard events to enable full functionality.

## Frequently Asked Questions

### How do I manually trigger the @‑mention dropdown without typing?

The dropdown is designed to react to text input events only. According to [`MentionDropdownController.ts`](https://github.com/YishenTu/claudian/blob/main/MentionDropdownController.ts), the `handleInputChange` method checks for a leading `@` character. To open it programmatically, you would need to insert `@` into the input element and dispatch an `input` event, allowing the 200 ms debounce logic to execute naturally.

### What is the difference between mentioning an MCP server and enabling it in the toolbar?

Mentioning a server via `@servername` inserts a text reference into your prompt and, if the server supports context‑saving, adds it to the active set managed by `setMentionedMcpServers`. Enabling a server via the toolbar wrench icon in [`InputToolbar.ts`](https://github.com/YishenTu/claudian/blob/main/InputToolbar.ts) toggles its operational state for the session but does not necessarily insert a text token into the prompt. Both actions ultimately populate the `MentionedMcpServers` set consumed by the chat controller.

### How does the `agents/` filter work in the dropdown?

When the search query after `@` begins with `agents/`, the `showMentionDropdown` method enters a special filter branch (lines 12‑22) that bypasses file and MCP listings. It queries the `AgentMentionProvider` for agents matching the substring after the slash, allowing rapid selection of specialized personas without clutter from vault files.

### Can I reference files outside my Obsidian vault using the dropdown?

Yes. The controller accepts a `getExternalContexts` callback that returns paths scanned by `externalContextScanner`. These external files appear alongside vault items in the dropdown, letting you attach source code, documentation, or data files stored outside your `.obsidian` directory.