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 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#

1
2

cd mcp-server
pip install -e .

2. Configure#

Set environment variables for the server:

1
2
3

export SCAIDRIVE_MCP_API_BASE_URL="https://scaidrive.scailabs.ai/api/v1"
export SCAIDRIVE_MCP_ACCESS_TOKEN="eyJhbGc..."
export SCAIDRIVE_MCP_ENABLE_SEMANTIC_SEARCH="true"

All settings use the SCAIDRIVE_MCP_ prefix. There is intentionally no .env file support — a stdio server runs with whatever working directory the client gives it, so configuration comes only from real environment variables.

3. Wire up to Claude Desktop#

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

{
  "mcpServers": {
    "scaidrive": {
      "command": "python",
      "args": ["-m", "scaidrive_mcp"],
      "env": {
        "SCAIDRIVE_MCP_API_BASE_URL": "https://scaidrive.scailabs.ai/api/v1",
        "SCAIDRIVE_MCP_ACCESS_TOKEN": "eyJhbGc...",
        "SCAIDRIVE_MCP_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#

1. User: "Summarize the quarterly goals for the Engineering team."
2. Claude calls list_shares → finds shr_engineering.
3. Claude calls semantic_search(query="quarterly goals", share_id="shr_engineering") → gets 10 relevant chunks.
4. Claude calls read_file on the top-ranked sources for full context.
5. 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.

• Capabilities are opt-in. The default toolset is read-only: keyword search, plus read tools (list_shares, list_folder, read_file, get_file_info). Everything with side effects or bulk content extraction is off by default and must be enabled explicitly via environment variables:

  • SCAIDRIVE_MCP_ENABLE_WRITE_OPERATIONS — create/update/delete files, folders, move/rename.
  • SCAIDRIVE_MCP_ENABLE_SHARING — external links, share members, invitations.
  • SCAIDRIVE_MCP_ENABLE_SEMANTIC_SEARCH — semantic_search and get_context (these return document chunk contents).
  • SCAIDRIVE_MCP_ENABLE_VERSION_HISTORY — list/restore file versions.

  Enable only what a given deployment needs. Sharing and write tools, in particular, can turn a prompt-injected document into a data-exfiltration or phishing vector, so leave them off unless required.

• read_file size cap. read_file refuses files larger than SCAIDRIVE_MCP_MAX_FILE_SIZE_MB (default 50 MB) to protect the agent's context and memory; fetch large files with a regular ScaiDrive client instead.

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

1

export SCAIDRIVE_MCP_LOG_LEVEL="DEBUG"

Common issues:

• "Authentication failed" — token expired or wrong URL. Check SCAIDRIVE_MCP_ACCESS_TOKEN and SCAIDRIVE_MCP_API_BASE_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.