---
title: MCP Server
path: advanced/mcp-server
status: published
---

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](/docs/scaidrive/api-guides/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.
- **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](/docs/scaidrive/api-guides/search)
- [Authentication](/docs/scaidrive/getting-started/authentication) — service tokens.