Metadata-Version: 2.4
Name: moatdrop-mcp
Version: 0.3.1
Summary: MCP server for Moatdrop — manage secure links from AI assistants
Project-URL: Homepage, https://moatdrop.com
Project-URL: Repository, https://github.com/Blocsmith/moatdrop
Author-email: Josh Cooper <josh@blocsmith.ai>
License-Expression: MIT
Keywords: ai,claude,mcp,moatdrop
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.2.0
Requires-Dist: pydantic>=2.0.0
Description-Content-Type: text/markdown

# Moatdrop MCP Server

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server for [Moatdrop](https://moatdrop.com) — manage secure, trackable links from AI assistants like Claude Desktop, Cursor, and Claude Code.

## Installation

```bash
pip install moatdrop-mcp
```

Or run directly with `uvx`:

```bash
uvx moatdrop-mcp
```

## Setup

### 1. Get an API Key

1. Log in to [Moatdrop](https://app.moatdrop.com)
2. Go to **Account > API Keys**
3. Create a new key and copy it

### 2. Configure Your AI Assistant

#### Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "moatdrop": {
      "command": "uvx",
      "args": ["moatdrop-mcp"],
      "env": {
        "MOATDROP_API_KEY": "mdp_your_key_here"
      }
    }
  }
}
```

#### Cursor

Add to your Cursor MCP config (`.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "moatdrop": {
      "command": "uvx",
      "args": ["moatdrop-mcp"],
      "env": {
        "MOATDROP_API_KEY": "mdp_your_key_here"
      }
    }
  }
}
```

#### Claude Code

```bash
claude mcp add moatdrop -- uvx moatdrop-mcp
```

Then set the environment variable:

```bash
export MOATDROP_API_KEY="mdp_your_key_here"
```

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `MOATDROP_API_KEY` | Yes | — | Your Moatdrop API key (`mdp_...`) |
| `MOATDROP_API_URL` | No | `https://api.moatdrop.com` | API base URL (for self-hosted or dev) |

## Available Tools

### Link Management

| Tool | Description |
|------|-------------|
| `create_link` | Create a secure link with URL, expiration, IP rules, click limits |
| `list_links` | List all your secure links |
| `get_link` | Get full details of a specific link |
| `update_link` | Update link name, expiration, click limits |
| `delete_link` | Permanently delete a link (requires `confirm=true`) |
| `enable_link` | Re-enable a revoked link |
| `disable_link` | Revoke/disable a link |

### Document Queries

| Tool | Description |
|------|-------------|
| `deep_extraction` | Ask a question and get an AI-synthesized answer from a shared file |

### Analytics & Account

| Tool | Description |
|------|-------------|
| `get_link_analytics` | Get raw access logs for a link |
| `get_analytics_summary` | Aggregated analytics: clicks, unique IPs, top countries, referrers |
| `get_account_info` | Your account details and plan tier |

## Available Resources

| URI | Description |
|-----|-------------|
| `moatdrop://links` | Summary list of all your links |
| `moatdrop://links/{id}` | Full details for a specific link |
| `moatdrop://links/{id}/analytics` | Access logs for a specific link |
| `moatdrop://account` | Your account info |

## Querying Files with AI Agents

MoatDrop lets you upload files, create secure links, and then query those files through AI agents using the MCP server. Here's how to set it up end to end.

### Step 1: Upload a file and create a secure link

Log in to [MoatDrop](https://moatdrop.com), click **+ Create Moat Link**, and upload your file (PDF, DOCX, XLSX, etc.). Once created, note the **moat link** — this is the short code in the secure URL (e.g., if the URL is `https://moatdrop.com/l/abc123`, the moat link is `abc123`).

You can find the moat link on the link detail page under **Moat Link**.

### Step 2: Create a share token

Share tokens let you grant someone query-only access to a specific file without sharing your full API key.

1. Go to the link detail page for your file
2. Expand **AI Agent Access > Show Setup**
3. Under **Create Share Token**, enter a name (e.g., "For Acme Corp")
4. Optionally set an expiration (hours) and max uses
5. Click **Create Token**
6. Copy the token (starts with `mds_`) — it's shown only once

### Step 3: Configure the MCP server

Give the share token to whoever needs to query the file. They add this to their AI assistant config:

#### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "moatdrop": {
      "command": "uvx",
      "args": ["moatdrop-mcp"],
      "env": {
        "MOATDROP_API_KEY": "mds_your_share_token_here"
      }
    }
  }
}
```

#### Cursor / VS Code

Add to `.cursor/mcp.json` or VS Code MCP settings:

```json
{
  "mcpServers": {
    "moatdrop": {
      "command": "uvx",
      "args": ["moatdrop-mcp"],
      "env": {
        "MOATDROP_API_KEY": "mds_your_share_token_here"
      }
    }
  }
}
```

#### Claude Code

```bash
claude mcp add moatdrop -- uvx moatdrop-mcp
```

Then set the environment variable:

```bash
export MOATDROP_API_KEY="mds_your_share_token_here"
```

### Step 4: Query the file

Once connected, ask your AI assistant to query the file using the moat link:

**Deep extraction (AI-synthesized answers):**

> "Use the deep_extraction tool with moat_link `abc123` and ask: What are the key findings in this report?"

The tool sends the full document to Gemini in a single call and returns a synthesized answer with PII scrubbed.

### Share token vs API key

| | Share Token (`mds_`) | API Key (`mdp_`) |
|---|---|---|
| **Scope** | Query access to one specific file | Full account access |
| **Safe to share** | Yes | No |
| **Can manage links** | No | Yes |
| **Can view analytics** | No | Yes |
| **Expiration** | Optional (configurable) | Optional |
| **Usage limits** | Optional (configurable) | None |

### Examples

Once configured, you can ask your AI assistant:

- "Use deep_extraction with hash abc123: What is the executive summary?"
- "Use deep_extraction with hash abc123: What date was the contract signed?"
- "Use deep_extraction with hash abc123: Pull the termination clauses from this contract"

## Development

```bash
# Clone and install in dev mode
cd mcp-server
pip install -e .

# Run with a local backend
MOATDROP_API_KEY=mdp_test MOATDROP_API_URL=http://localhost:8000 moatdrop-mcp

# Run tests
pip install pytest
pytest tests/
```

## License

MIT
