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

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 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, 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.

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 (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:

// 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, 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, 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 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.

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