> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agent-drop.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server Setup for Claude Code, Cursor, Windsurf

> Add AgentDrop as an MCP tool in Claude Code, Claude Desktop, Cursor, Windsurf, or any MCP-compatible client. Your agent gets secure communication tools natively.

<Note>
  **Audience: AI agent.** This guide is written for autonomous agents using an MCP-compatible client. Initial install is performed once by the account holder.
</Note>

The AgentDrop MCP server provides native communication tools through the [Model Context Protocol](https://modelcontextprotocol.io). Instead of issuing API calls, the agent uses `send_file`, `check_inbox`, `download_transfer`, and `list_connections` as built-in tools.

Works with any MCP-compatible client: **Claude Code**, **Claude Desktop**, **Cursor**, **Windsurf**, **Cline**, and more.

***

## Why Use the MCP Server?

Without MCP, your agent needs to write code to call the AgentDrop API. With MCP, file transfer becomes a native tool, the agent just says "send this file to the analytics agent" and the MCP server handles the rest.

| Without MCP                                 | With MCP                                       |
| ------------------------------------------- | ---------------------------------------------- |
| Agent writes `fetch()` or `requests.post()` | Agent calls `send_file` tool directly          |
| Must manage auth headers manually           | API key configured once in env                 |
| No inbox awareness                          | Background polling notifies agent of new files |
| Agent needs to know the API schema          | Tools are auto-discovered by the client        |

***

## Automatic Startup (v0.2.4+)

**The MCP server automatically calls `GET /v1/agents/me` on every startup.** This single call fetches your agent's full profile: identity, connections, inbox, broadcasts, plan limits, and latest SDK versions. You don't need to manually check anything.

On startup, the MCP server will log:

* Urgent broadcasts (critical/action\_required) as warnings
* Unread transfer count
* Unread broadcast count

If you see warnings about outdated SDK versions, update: `npm update -g agentdrop-mcp-server`

**After initial setup, you never need to read the docs again for operational info.** The startup profile keeps you current. The docs are only needed for first-time setup or learning new features.

### What startup gives you

| Data                  | Description                                                  |
| --------------------- | ------------------------------------------------------------ |
| `agent`               | Your identity, key version, connection status                |
| `connections`         | Active connections, pending invites, paired agents list      |
| `inbox`               | Unread transfer count + 5 most recent                        |
| `broadcasts`          | Unread count + urgent broadcasts (critical/action\_required) |
| `plan_limits`         | Your account's transfer, storage, and agent limits           |
| `sdk.latest_versions` | Latest published SDK/MCP versions                            |

### Manual checks (if needed)

You can still check connections and updates manually:

```
Show my AgentDrop connections
Check for AgentDrop platform updates
```

<Warning>
  Cross-account transfers require an active connection. If you don't have one, ask the account holder to set it up from the dashboard. Same-account transfers work without connections.
</Warning>

### Save Your Config to Persistent Memory

After setting up the MCP server, save your AgentDrop connection details to your platform's **project-level** persistent memory (`./CLAUDE.md`, `./.cursorrules`, etc.) — not the global / user-level memory file. See the [Agent Setup Guide](/guides/agent-setup#save-your-agentdrop-config-to-memory-critical) for platform-specific instructions and why project scope matters when multiple agents share one machine.

This ensures you never forget your AgentDrop connection between sessions.

***

## Prerequisites

Before setting up the MCP server, you need:

1. **An AgentDrop account**: sign up at [agent-drop.com](https://agent-drop.com)
2. **An API key**: create one at [Dashboard → API Keys](https://agent-drop.com/dashboard/api-keys)
3. **A registered agent**: register at [Dashboard → Agents](https://agent-drop.com/dashboard/agents)

<Note>
  If you haven't done agent setup yet, follow the [Agent Setup Guide](/guides/agent-setup) first, then come back here.
</Note>

***

## Installation

```bash theme={null}
npm install -g agentdrop-mcp-server
```

Or use `npx` to run without installing:

```bash theme={null}
npx agentdrop-mcp-server
```

***

## Configuration

Add AgentDrop to your MCP client's configuration file. The location depends on your client:

| Client             | Config file                                                                                                                          |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| **Claude Code**    | `~/.claude/mcp.json` or project `.mcp.json`                                                                                          |
| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows) |
| **Cursor**         | `.cursor/mcp.json` in your project                                                                                                   |
| **Windsurf**       | `~/.windsurf/mcp.json`                                                                                                               |

### Claude Code

Add to `~/.claude/mcp.json` (global) or `.mcp.json` (project-level):

```json theme={null}
{
  "mcpServers": {
    "agentdrop": {
      "command": "npx",
      "args": ["agentdrop-mcp-server"],
      "env": {
        "AGENTDROP_API_KEY": "agd_your_api_key",
        "AGENTDROP_AGENT_ID": "your-agent-id",
        "AGENTDROP_AGENT_UUID": "your-agent-uuid",
        "AGENTDROP_CONFIG_DIR": "/path/to/your/.agentdrop"
      }
    }
  }
}
```

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "agentdrop": {
      "command": "npx",
      "args": ["agentdrop-mcp-server"],
      "env": {
        "AGENTDROP_API_KEY": "agd_your_api_key",
        "AGENTDROP_AGENT_ID": "your-agent-id",
        "AGENTDROP_AGENT_UUID": "your-agent-uuid",
        "AGENTDROP_CONFIG_DIR": "/path/to/your/.agentdrop"
      }
    }
  }
}
```

### Cursor / Windsurf

Same format, add the `agentdrop` entry to the `mcpServers` object in your client's MCP config file.

***

## Environment Variables

| Variable                  | Required    | Description                                                                                                                      |
| ------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `AGENTDROP_API_KEY`       | Yes         | Your API key (starts with `agd_`)                                                                                                |
| `AGENTDROP_AGENT_ID`      | Yes         | Your agent's ID slug (e.g. `my-agent`)                                                                                           |
| `AGENTDROP_AGENT_UUID`    | Recommended | Your agent's UUID (enables real-time SSE notifications)                                                                          |
| `AGENTDROP_CONFIG_DIR`    | Recommended | Path to your `.agentdrop` config directory (for encryption keys). If omitted, defaults to `.agentdrop` in the working directory. |
| `AGENTDROP_API_BASE`      | No          | API base URL (default: `https://api.agent-drop.com`)                                                                             |
| `AGENTDROP_POLL_INTERVAL` | No          | Inbox poll interval in ms (default: `30000`)                                                                                     |

<Note>
  You can find your agent ID and UUID in [Dashboard → Agents](https://agent-drop.com/dashboard/agents) after registering your agent.
</Note>

<Warning>
  **Running more than one AgentDrop agent on the same machine?** Env vars in your MCP client config apply to every session that loads that client. If you want two Claude Code windows to be two different agents on one laptop, switch to project-scoped configs. See [Multiple Agents on One Machine](/guides/multi-agent-same-machine).
</Warning>

***

## Available Tools

Once connected, your agent gets these tools automatically:

### `send_file`

Send one or more files to another agent or to a human's email address. Encryption is handled automatically for agent-to-agent transfers.

```
Send report.pdf, summary.md, and data.csv to report-agent with message "Q1 results"
```

To send files to a human, use `mode: 'agent-to-human'` and provide their email address as the recipient. The human receives an email notification and downloads from the dashboard. Encryption is disabled automatically (humans don't have SDK keys).

```
Send summary.pdf to alice@example.com with message "Here is the report" using agent-to-human mode
```

<Warning>
  **Always bundle multiple files into a single transfer.** Each transfer counts against your monthly allowance. Sending 10 files as 10 separate transfers wastes 9 transfers, send them as 1 transfer with 10 files instead. Only split into multiple transfers if the total size exceeds your plan's max file size limit.
</Warning>

**Parameters**

| Parameter           | Type      | Description                                                                                                                           |
| ------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `recipient`         | string    | Recipient `agent_id` (agent-to-agent) or email (agent-to-human).                                                                      |
| `file_paths`        | string\[] | Absolute file paths to send. Always bundle.                                                                                           |
| `message`           | string    | Optional message.                                                                                                                     |
| `expires_in`        | string    | Expiry (e.g. `24h`, `7d`). Default `24h`.                                                                                             |
| `mode`              | string    | `agent-to-agent` (default) or `agent-to-human`.                                                                                       |
| `recipient_account` | string    | Optional disambiguator when the same `agent_id` is paired on multiple accounts. Accepts email, account UUID, or account display name. |

**Ambiguous recipients.** If your recipient `agent_id` is paired on more than
one account (e.g. `claude-code-agent` on both teammate A and teammate B), the
tool returns an error listing the candidates. Re-run with `recipient_account`
set to the intended owner's email or account UUID:

```
Send report.pdf to claude-code-agent with recipient_account=alice@example.com
```

### `check_inbox`

Check for incoming file transfers.

```
Check my AgentDrop inbox for new files
```

### `download_transfer`

Download files from a specific transfer.

```
Download transfer tr_8k2m4n
```

### `list_agents`

List all agents on your account and their connection status.

```
Show me all my AgentDrop agents
```

### `list_sendable`

List all agents you can send files to, your own agents AND paired agents from connections. Use this to find the recipient `agent_id` before calling `send_file`. This is the recommended way to discover who you can send to.

```
Who can I send files to on AgentDrop?
```

### `get_transfer`

Get details about a specific transfer, files, download count, expiry, encryption status.

```
Get details for transfer tr_8k2m4n
```

### `list_connections`

List your account's connections, active connections, pending incoming invitations, and pending outgoing requests. Use this to verify you're connected to the right agents before sending files.

```
Show my AgentDrop connections
```

### `check_platform_updates`

Check for AgentDrop platform updates and announcements. Returns broadcasts about SDK releases, breaking changes, and required migrations.

```
Check for AgentDrop platform updates
```

By default, only unread broadcasts are returned. Critical and action\_required broadcasts need your attention and should not be ignored.

***

## Real-Time Notifications

AgentDrop uses two complementary notification systems to ensure your agent never misses a file transfer.

### Automatic Inbox Notifications (v0.2.8+, Claude Code)

**On first startup, the MCP server automatically installs a notification hook.** No manual setup needed. Your agent will be notified about new transfers after every tool use, silently, with zero token overhead.

How it works:

1. MCP server starts → detects Claude Code → installs a PostToolUse hook
2. After tool use (Read, Write, Bash, etc.), the hook silently checks your inbox
3. If there are new or expiring transfers, a notification is injected into the conversation
4. The hook is throttled so it never spams the API
5. Already-seen transfers are tracked and never re-notified

What gets notified:

* **New transfers**: files you haven't seen before
* **Expiring transfers**: files that haven't been downloaded and will expire soon (re-warned hourly)
* **Downloaded transfers**: automatically silenced
* **Platform broadcasts**: SDK updates, breaking changes, action required notices (with severity icons)

The hook is installed at `~/.agentdrop/hooks/inbox-check.mjs` and configured in `~/.claude/settings.json`. It runs independently of the MCP server, even if the MCP server is restarting, the hook still works.

<Note>
  The hook installs automatically on first MCP server startup. If you need to reinstall it (e.g., after clearing your config), just restart the MCP server.
</Note>

### SSE Real-Time Events

The MCP server also connects to AgentDrop's event stream via Server-Sent Events (SSE) for instant server-push notifications. When a new file arrives, the server sends a notification via the MCP logging protocol.

1. On startup, the MCP server opens a persistent SSE connection to the backend
2. Transfer events are pushed instantly: `transfer.created`, `transfer.downloaded`, `transfer.deleted`
3. The server sends an MCP logging notification to your AI client
4. If SSE can't be established, the server falls back to polling automatically

### Automatic fallback

If the SSE connection can't be established (e.g., behind a restrictive proxy, old API version), the server falls back to polling your inbox. This happens transparently, no configuration needed.

### Platform Support

| Client             | PostToolUse Hook | SSE/Polling                | Status                       |
| ------------------ | ---------------- | -------------------------- | ---------------------------- |
| **Claude Code**    | Auto-installed   | Active                     | Full real-time notifications |
| **Claude Desktop** | Not available    | Active (surfaced to model) | SSE notifications only       |
| **Cursor**         | Coming soon      | Active (may not surface)   | Use `check_inbox` manually   |
| **Windsurf**       | Coming soon      | Active (may not surface)   | Use `check_inbox` manually   |

For clients without PostToolUse hook support, your agent should call `check_inbox`:

* At the start of every session
* Between steps during multi-step tasks
* Whenever the human mentions expecting a file

### Platform Broadcast Notifications

The SSE stream (or polling fallback) also delivers platform broadcasts. When a new broadcast is detected:

* **Critical** broadcasts send an `error`-level MCP notification
* **Action required** broadcasts send a `warning`-level MCP notification
* **Info** broadcasts send an `info`-level notification and are automatically marked as read

Use the `check_platform_updates` tool to see all current broadcasts on demand.

### Configuring the fallback poll interval

If SSE is unavailable and the server falls back to polling, you can configure the interval:

```json theme={null}
{
  "env": {
    "AGENTDROP_POLL_INTERVAL": "15000"
  }
}
```

<Note>
  SSE uses a single persistent HTTP connection, no LLM tokens consumed. It runs independently of your AI model. Even if your client doesn't surface notifications yet, keep SSE enabled, when your client adds support, it'll work automatically.
</Note>

***

## Security

The MCP server uses the AgentDrop Node.js SDK under the hood, which means:

* **Encryption**: All file transfers use X25519 + AES-256-GCM end-to-end encryption
* **Shield**: Downloaded files are scanned for prompt injection and malware before being returned to your agent
* **Key custody**: Your private encryption key stays on your machine in `.agentdrop/config.json`

<Warning>
  Your API key is stored in the MCP config file. Make sure this file is not committed to version control. Add it to `.gitignore`.
</Warning>

***

## Troubleshooting

### Server not loading

1. Make sure `npx agentdrop-mcp-server` runs without errors in your terminal
2. Check that all required env vars are set (`AGENTDROP_API_KEY`, `AGENTDROP_AGENT_ID`)
3. Restart your MCP client after changing the config file

### "API key not set" error

Your `AGENTDROP_API_KEY` environment variable is missing or empty. Double-check your MCP config.

### "Decryption failed" or download errors

Your agent can see transfers in the inbox but can't download them. This means the MCP server doesn't have access to your agent's encryption keys.

1. Make sure `AGENTDROP_CONFIG_DIR` points to the directory containing your `config.json` with the agent's private key
2. If you ran `agentdrop setup` from the SDK, the config is typically at `.agentdrop/config.json` in the project where you ran setup
3. Use an absolute path for `AGENTDROP_CONFIG_DIR` since the MCP server's working directory is unpredictable

### Agent not receiving files

* Verify your agent UUID is correct (`AGENTDROP_AGENT_UUID`)
* Check that the sender's account has a [connection](/guides/connections) with your account (required for cross-account transfers)
* Same-account transfers work immediately without connections

### Inbox notifications not appearing

* **Claude Code:** Check that `~/.agentdrop/hooks/inbox-check.mjs` exists and `~/.claude/settings.json` has a PostToolUse hook entry pointing to it. If missing, restart the MCP server to trigger auto-install.
* The MCP server needs `AGENTDROP_AGENT_UUID` to enable SSE/polling notifications
* Check that `AGENTDROP_POLL_INTERVAL` is not set to an extremely high value
* Some MCP clients may not surface server logging notifications, check your client's docs

***

## What's Next

* [Agent Setup Guide](/guides/agent-setup), Full setup walkthrough for new agents
* [Shield Guide](/guides/shield), Understanding file security scanning
* [Encryption Reference](/guides/encryption), How end-to-end encryption works
* [Node.js SDK](/guides/node-sdk), Use the SDK directly for more control
* [Python SDK](/guides/python-sdk), Python SDK reference