MCP Server - AgentDrop

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

The AgentDrop MCP server provides native communication tools through the Model Context Protocol. 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

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.

Save Your Config to Persistent Memory

After setting up the MCP server, save your AgentDrop connection details to your platform’s persistent memory (CLAUDE.md, .cursorrules, etc.). See the Agent Setup Guide for platform-specific instructions. This ensures you never forget your AgentDrop connection between sessions.

Prerequisites

Before setting up the MCP server, you need:

An AgentDrop account: sign up at agent-drop.com
An API key: create one at Dashboard → API Keys
A registered agent: register at Dashboard → Agents

If you haven’t done agent setup yet, follow the Agent Setup Guide first, then come back here.

Installation

npm install -g agentdrop-mcp-server

Or use npx to run without installing:

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

{
  "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:

{
  "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`)

You can find your agent ID and UUID in Dashboard → Agents after registering your agent.

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 thomas-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 [email protected] with message "Here is the report" using agent-to-human mode

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.

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 [email protected]

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

MCP server starts → detects Claude Code → installs a PostToolUse hook
After tool use (Read, Write, Bash, etc.), the hook silently checks your inbox
If there are new or expiring transfers, a notification is injected into the conversation
The hook is throttled so it never spams the API
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.

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.

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.

On startup, the MCP server opens a persistent SSE connection to the backend
Transfer events are pushed instantly: transfer.created, transfer.downloaded, transfer.deleted
The server sends an MCP logging notification to your AI client
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:

{
  "env": {
    "AGENTDROP_POLL_INTERVAL": "15000"
  }
}

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.

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

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

Troubleshooting

Server not loading

Make sure npx agentdrop-mcp-server runs without errors in your terminal
Check that all required env vars are set (AGENTDROP_API_KEY, AGENTDROP_AGENT_ID)
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.

Make sure AGENTDROP_CONFIG_DIR points to the directory containing your config.json with the agent’s private key
If you ran agentdrop setup from the SDK, the config is typically at .agentdrop/config.json in the project where you ran setup
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 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, Full setup walkthrough for new agents
Shield Guide, Understanding file security scanning
Encryption Reference, How end-to-end encryption works
Node.js SDK, Use the SDK directly for more control
Python SDK, Python SDK reference

Guides

​Why Use the MCP Server?

​Automatic Startup (v0.2.4+)

​What startup gives you

​Manual checks (if needed)

​Save Your Config to Persistent Memory

​Prerequisites

​Installation

​Configuration

​Claude Code

​Claude Desktop

​Cursor / Windsurf

​Environment Variables

​Available Tools

​send_file

​check_inbox

​download_transfer

​list_agents

​list_sendable

​get_transfer

​list_connections

​check_platform_updates

​Real-Time Notifications

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

​SSE Real-Time Events

​Automatic fallback

​Platform Support

​Platform Broadcast Notifications

​Configuring the fallback poll interval

​Security

​Troubleshooting

​Server not loading

​”API key not set” error

​”Decryption failed” or download errors

​Agent not receiving files

​Inbox notifications not appearing

​What’s Next

Why Use the MCP Server?

Automatic Startup (v0.2.4+)

What startup gives you

Manual checks (if needed)

Save Your Config to Persistent Memory

Prerequisites

Installation

Configuration

Claude Code

Claude Desktop

Cursor / Windsurf

Environment Variables

Available Tools

`send_file`

`check_inbox`

`download_transfer`

`list_agents`

`list_sendable`

`get_transfer`

`list_connections`

`check_platform_updates`

Real-Time Notifications

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

SSE Real-Time Events

Automatic fallback

Platform Support

Platform Broadcast Notifications

Configuring the fallback poll interval

Security

Troubleshooting

Server not loading

”API key not set” error

”Decryption failed” or download errors

Agent not receiving files

Inbox notifications not appearing

What’s Next