Model Context Protocol (MCP) Server¶

The Multi-Storage Client MCP Server enables conversational interaction with MSC through AI assistants and LLM clients using natural language, removing the need to memorize API methods or CLI commands.

Overview¶

Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to Large Language Models (LLMs). The MSC MCP Server implements this protocol, allowing AI assistants like Cursor, Claude Desktop, and others to interact with your storage backends through conversational interfaces.

Key Benefits:

Natural Language Interface: Ask “Show me all files under prefix /project1/part2/” instead of learning the list() method parameters or msc ls command syntax
Pattern Matching: Request “Find all .log files from last week” instead of constructing complex glob patterns
Simplified Operations: Say “Copy all model checkpoints from local to S3” instead of writing sync scripts
Interactive Workflows: Manage storage with conversational confirmation and guidance

The MCP Server leverages MSC’s existing authentication and configuration system, so your credentials and storage profiles work seamlessly without additional setup.

Requirements¶

Python 3.10 or higher - MCP Server uses features only available in Python 3.10+
Multi-Storage Client with the mcp extra and storage provider extras for each backend you intend to use
An MCP-compatible client such as Cursor, Claude Desktop, or other MCP clients

See the Installation guide for complete installation instructions.

Important

The msc CLI must be accessible from your shell’s PATH. If msc mcp-server --help doesn’t work:

Verify msc is in PATH: Run which msc (macOS/Linux) or where msc (Windows)
macOS/Homebrew: Ensure /opt/homebrew/bin or your virtualenv’s bin directory is in PATH
Windows: Ensure your Python installation’s Scripts directory is in PATH
Virtual environment: Activate your Python virtual environment if you installed MSC in one

Starting the Server¶

The MCP Server runs locally on your machine and is started automatically by your MCP client (e.g., Cursor) when configured. See Configuration for setup instructions.

You can also start the server manually for testing or debugging:

# Start with default configuration discovery
msc mcp-server start

# Start with a specific configuration file
msc mcp-server start --config /path/to/config.yaml

# Start with verbose logging for debugging
msc mcp-server start --config /path/to/config.yaml --verbose

Configuration¶

Understanding stdio Communication¶

The MCP Server communicates with AI assistants using the stdio protocol (standard input/output), which sends and receives JSON-RPC 2.0 messages over stdout and stdin. Any output to stdout will interfere with the MCP protocol and cause communication failures.

MSC progress bars are written to stderr (not stdout), so no special configuration is needed for MSC’s own output. However, if you use optional extras (e.g., boto3, google-cloud-storage, azure-storage-blob, huggingface), some third-party dependencies may write to stdout. You are responsible for configuring these dependencies to suppress stdout output through environment variables (e.g., HF_HUB_DISABLE_PROGRESS_BARS for HuggingFace Hub).

Cursor Configuration¶

To use the MSC MCP Server with Cursor, add the following configuration to your Cursor settings file:

macOS/Linux: ~/.cursor/mcp.json
Windows: %APPDATA%\Cursor\mcp.json
Or via Cursor UI: Settings → Features → Model Context Protocol

Basic Cursor configuration for MSC MCP Server.¶

{
  "mcpServers": {
    "Multi-Storage Client": {
      "command": "msc",
      "args": [
        "mcp-server",
        "start"
      ]
    }
  }
}

Advanced Cursor configuration with custom config file.¶

{
  "mcpServers": {
    "Multi-Storage Client": {
      "command": "msc",
      "args": [
        "mcp-server",
        "start",
        "--config", "/path/to/msc_config.yaml"
      ]
    }
  }
}

Configuration Parameters:

command: The msc CLI command (must be installed and accessible in your PATH)
args: Arguments to pass to the MCP server
- mcp-server start: Command to start the MCP server
- --config: Optional path to MSC configuration file
env: Optional environment variables (e.g., to suppress stdout output from third-party dependencies)

Note

If you don’t specify a --config path, MSC will use its standard configuration discovery mechanism, checking locations like ~/.msc_config.yaml, MSC_CONFIG environment variable, etc. See Quickstart for details.

Other MCP Clients¶

The MSC MCP Server follows the standard MCP protocol and can be used with any MCP-compatible client. Configuration will be similar to the Cursor example above, though the exact format may vary by client. Refer to your MCP client’s documentation for specific configuration instructions.

MSC Configuration¶

The MCP Server uses your existing MSC configuration file to determine which storage profiles and backends are available. No special MCP-specific configuration is needed in your MSC config.

Example MSC configuration that works with MCP Server.¶

profiles:
  my-s3-bucket:
    storage_provider:
      type: s3
      options:
        base_path: my-bucket
        region_name: us-east-1

  my-gcs-bucket:
    storage_provider:
      type: gcs
      options:
        base_path: my-gcs-bucket

  local-storage:
    storage_provider:
      type: file
      options:
        base_path: /mnt/data

Available Tools¶

The MCP Server provides the following tools for storage operations. Your AI assistant will automatically use these tools when you make requests in natural language.

msc_list¶

Lists files and directories from a storage location.

Parameters:

url (required): Storage URL to list (e.g., msc://profile/path/, s3://bucket/prefix/)

URLs can use either msc://profile/path/ format (using profiles from your MSC config) or provider-native URLs like s3://bucket/prefix/. A trailing slash typically indicates a directory/prefix.
start_after: Start listing after this key (exclusive, for pagination)
end_at: End listing at this key (inclusive, for pagination)

Listings are lexicographically ordered by key. start_after and end_at apply to this ordering.
include_directories: Whether to include directories in results (default: false)
attribute_filter_expression: Filter results by attributes
show_attributes: Include attributes in the response (default: false)
limit: Maximum number of objects to return

Example prompts:

“List all files in my production-s3 profile under the data/ prefix”
“Show me the first 10 files in my-profile under datasets/”
“List directories in my backup-storage profile”

msc_info¶

Retrieves detailed metadata about a specific file or directory.

Parameters:

url (required): Full path to the object (e.g., msc://profile/path/file.txt)

Example prompts:

“Get information about model.pkl in my training-data profile”
“What’s the size of dataset.csv in my-s3-bucket?”
“When was model.pkl in the production profile last modified?”

msc_upload_file¶

Uploads a file from the local filesystem to storage.

Parameters:

url (required): Destination URL where file will be stored
local_path (required): Local path of the file to upload
attributes: Optional metadata attributes to attach to the file

Example prompts:

“Upload my local model.pkl to the production-s3 profile”
“Copy /tmp/data.csv to datasets/ in my backup-bucket profile”

msc_download_file¶

Downloads a file from storage to the local filesystem.

Parameters:

url (required): URL of the file to download
local_path (required): Local path where file should be saved

Example prompts:

“Download checkpoint.pkl from my training profile to /tmp/”
“Get model.pkl from the production-s3 profile and save it to /tmp/”

msc_delete¶

Deletes files or directories from storage.

Parameters:

url (required): URL of the object to delete
recursive: Whether to delete directories recursively (default: false)

Example prompts:

“Delete old_checkpoint.pkl from my training profile”
“Remove all files in the temp/ directory in staging-storage”

Warning

Deletion operations are permanent. The AI assistant will typically ask for confirmation before executing delete operations.

msc_copy¶

Copies a file within the same storage profile.

Parameters:

source_url (required): Source file URL
target_url (required): Target file URL

Example prompts:

“Copy model.pkl to model_backup.pkl in my production profile”
“Duplicate checkpoint.pkl within the training-data profile”

Note

msc_copy is designed for copying files within the same storage profile (e.g., copying msc://my-s3-bucket/file.txt to msc://my-s3-bucket/file_backup.txt).

To copy files between different profiles (e.g., from local-storage to production-s3), use msc_sync or download then upload.

msc_sync¶

Synchronizes files between different storage locations or profiles.

Parameters:

source_url (required): Source storage URL
target_url (required): Target storage URL
delete_unmatched_files: Delete files at target not present at source (default: false)
preserve_source_attributes: Preserve source file metadata (default: false)

Example prompts:

“Sync data/ from my local-storage profile to production-s3”
“Copy all model checkpoints from my-gcs profile to local-storage”
“Mirror datasets/ from primary-bucket to backup-bucket profile”

msc_sync_replicas¶

Synchronizes files from primary storage to configured replica storage locations. See Replicas for more information about replica configuration.

Parameters:

source_url (required): Source storage URL
replica_indices: Optional list of specific replica indices to sync (0-based)
delete_unmatched_files: Delete files at replicas not present at source (default: false)

Example prompts:

“Sync datasets/ from primary-storage profile to all configured replicas”
“Mirror data/ from production to replica 0 only”
“Update replicas with latest files from the main-bucket profile”

msc_is_file¶

Checks whether a URL points to a file rather than a directory.

Parameters:

url (required): URL to check

Example prompts:

“Is data/model.pkl in my training profile a file or directory?”
“Check if model.pkl exists as a file in the production-s3 profile”

msc_is_empty¶

Checks whether a storage location contains any objects.

Parameters:

url (required): URL to check

Example prompts:

“Is the temp/ directory empty in my staging profile?”
“Check if the backup-bucket profile has any files”

Available Prompts¶

The MCP Server provides a single prompt to help AI assistants understand MSC functionality and guide users effectively.

msc_help¶

Provides comprehensive help information about MSC configuration, usage, and available MCP tools. This prompt gives your AI assistant context on:

Supported storage backends (S3, GCS, Azure, local filesystem, etc.)
Available MCP tools and their parameters
Configuration file locations and formats
URL formats for accessing storage
General usage guidance

How it works:

The msc_help tool provides context to your AI assistant automatically—you don’t need to invoke it directly. When you ask general questions about MSC, the AI assistant uses this information to provide accurate answers.

For example, you can ask your assistant:

“How do I use MSC with the MCP Server?”
“What can I do with Multi-Storage Client?”
“Help me understand MSC configuration”
“What MCP tools are available?”

The AI will automatically consult the msc_help context to formulate its response.

Examples¶

Conversational File Operations¶

Instead of writing:

from multistorageclient import StorageClient, StorageClientConfig

client = StorageClient(StorageClientConfig.from_file(profile="my-s3"))
for obj in client.list(path="datasets/images/", include_directories=False):
    print(obj.name, obj.size)

You can simply ask:

“Show me all files in my my-s3 profile under datasets/images/”

Or:

“List files in the datasets/images folder using the my-s3-bucket profile”

Pattern Matching and Filtering¶

Instead of using glob patterns:

import multistorageclient as msc

for file in msc.glob("msc://my-profile/logs/*.log"):
    if file.last_modified > some_date:
        print(file)

You can simply ask:

“Find all .log files from last week in my my-profile logs folder”

Or:

“Show me .log files modified in the last 7 days in the production-storage profile”

Bulk Operations¶

Instead of writing sync scripts:

from multistorageclient import StorageClient, StorageClientConfig

source = StorageClient(StorageClientConfig.from_file(profile="local"))
target = StorageClient(StorageClientConfig.from_file(profile="s3"))

target.sync_from(source, "checkpoints/", "checkpoints/")

You can simply ask:

“Sync all model checkpoints from my local-storage profile to my-s3-bucket profile”

Or:

“Copy checkpoints/ from local to production-s3”

Interactive Management¶

Instead of carefully constructing delete commands:

msc rm msc://my-bucket/temp/ --recursive

You can simply ask:

“Delete files in my my-bucket profile temp directory older than 30 days”

Or:

“Remove old files from temp/ in staging-storage”

The AI assistant can help you identify the right files, confirm the operation, and execute it safely.