MCP Server

ScaiDrive ships an MCP (Model Context Protocol) server that exposes shares, files, and search as tools Claude and other MCP-compatible LLMs can call. Point Claude Desktop at it and your AI assistant can list files, read content, and answer questions over your document library.

What it is#

The MCP server is a separate process (mcp-server/ in the repository) that speaks MCP on stdio. It authenticates to the ScaiDrive API using a user or service token and exposes a curated set of tools and resources.

What it exposes#

Tools:

Tool	Purpose
`list_shares`	List shares the token can access
`list_folder`	List folder contents (`share_id`, `folder_id`)
`read_file`	Read file content as text (`file_id`)
`get_file_info`	File metadata (`file_id`)
`search`	Keyword search (`query`, optional `share_id`, `file_types`, `limit`)
`semantic_search`	Vector search (`query`, optional `share_id`, `limit`) — requires vectorization enabled

Tool responses are JSON objects matching the ScaiDrive API shape — easy for the LLM to reason about.

Resources: files and folders exposed via MCP resource URIs. Template: scaidrive://share/{share_id}/{file_or_folder_id}. Listing a folder as a resource returns child URIs; reading a file resource returns the content.

Setup#

1. Install#

bash
cd mcp-server
pip install -e .

2. Configure#

Set environment variables for the server:

bash
export SCAIDRIVE_URL="https://scaidrive.scailabs.ai"
export SCAIDRIVE_TOKEN="eyJhbGc..."
export SCAIDRIVE_ENABLE_SEMANTIC_SEARCH="true"

3. Wire up to Claude Desktop#

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent on Windows / Linux:

json
{
  "mcpServers": {
    "scaidrive": {
      "command": "python",
      "args": ["-m", "scaidrive_mcp"],
      "env": {
        "SCAIDRIVE_URL": "https://scaidrive.scailabs.ai",
        "SCAIDRIVE_TOKEN": "eyJhbGc...",
        "SCAIDRIVE_ENABLE_SEMANTIC_SEARCH": "true"
      }
    }
  }
}

Restart Claude Desktop. Ask "what shares do I have access to?" and you'll see the tool invocation.

4. Use from other MCP clients#

The MCP server speaks standard MCP over stdio. Any MCP client (Claude Code, custom agents, etc.) can launch it the same way.

Permissions model#

The MCP server acts as whoever's token it's configured with. If the token belongs to Alice, the MCP server can only see what Alice can see — the same ACL checks apply as for direct API access.

For service deployments, use a dedicated service token with narrowly-scoped permissions, and keep tokens short-lived when possible.

Semantic search#

semantic_search only works when the tenant has vectorization configured (a provider plus a policy). If not configured, the tool returns SERVICE_UNAVAILABLE. See Search for setup.

With semantic search enabled, you can ask Claude things like "what does our 2026 pricing strategy say about volume discounts?" and Claude will invoke semantic_search, read the relevant chunks, and answer with citations.

Typical interaction#

User: "Summarize the quarterly goals for the Engineering team."
Claude calls list_shares → finds shr_engineering.
Claude calls semantic_search(query="quarterly goals", share_id="shr_engineering") → gets 10 relevant chunks.
Claude calls read_file on the top-ranked sources for full context.
Claude answers with a summary and inline citations.

No indexing step in your application. The MCP server hits the same ScaiDrive search API your web UI uses.

Limitations#

Token management. MCP Desktop configs store tokens in plain JSON on the user's machine. For team deployments, consider wrapping the MCP server with a short-lived-token issuance layer.
Binary files. read_file works on text files and files whose MIME types are text/* or common office formats (the server extracts text). For arbitrary binaries, the LLM gets a MIME type and a file ID but not content.
Write operations. The default toolset is read-only. Write tools (upload, modify) are available in the configuration but disabled by default — consult the mcp-server/ README if you need them.
Scale. Each Claude session runs one MCP server process. For very large document libraries, consider filtering by share at query time.

Debugging#

Claude Desktop shows MCP server output in a log pane. Enable verbose logging:

bash
export SCAIDRIVE_MCP_LOG_LEVEL="DEBUG"

Common issues:

"Authentication failed" — token expired or wrong URL. Check SCAIDRIVE_TOKEN and SCAIDRIVE_URL.
"No shares visible" — the token's user has no share memberships. Check via GET /api/v1/users/me/shares directly.
"Semantic search not available" — the tenant hasn't configured a vectorization provider, or it's temporarily unhealthy. Hit GET /api/v1/search/health.

What's next#

Search Guide
Authentication — service tokens.