AgentDrop MCP Server

0.2.22 · active · verified Wed Apr 22

The `agentdrop-mcp-server` package provides the Model Context Protocol (MCP) server for the AgentDrop ecosystem, facilitating secure, structured communication and tool access for AI agents. It acts as a core infrastructure component, enabling agents to send and receive files, manage connections, and execute predefined tools like `send_file` and `download_transfer` without needing to implement underlying cryptographic details (X25519/AES-256-GCM). The current stable version is 0.2.22, indicating an active development phase, though release cadence is not explicitly stated. Key differentiators include its tight integration with AgentDrop for AI agent communication, automatic encryption/decryption of file transfers, and self-updating agent profile retrieval, positioning it as a dedicated agent communication backbone rather than a general-purpose server.

Common errors

```
Error: Command 'agentdrop-mcp-server' not found.
```
cause The `agentdrop-mcp-server` package was not installed globally or `npx` cannot locate it.

fix Ensure you have installed the package globally using `npm install -g agentdrop-mcp-server` or that `npx` is correctly configured in your PATH.
```
Error: Missing required environment variable: AGENTDROP_API_KEY
```
cause The MCP server requires specific environment variables (`AGENTDROP_API_KEY`, `AGENTDROP_AGENT_ID`, `AGENTDROP_AGENT_UUID`, `AGENTDROP_CONFIG_DIR`) to function, and one was not provided.

fix Set all required environment variables in your MCP client's configuration or directly in your shell before launching the server. For example: `export AGENTDROP_API_KEY=agd_your_key`.
```
Node.js version mismatch: Expected >=18.0.0 but found v16.x.x
```
cause Your current Node.js version does not meet the minimum requirement specified in the package's `engines` field.

fix Upgrade your Node.js installation to version 18.0.0 or higher. Using `nvm install 18 && nvm use 18` is recommended for managing Node.js versions.

Warnings

gotcha Do NOT manually implement encryption or decryption logic. The `send_file` and `download_transfer` tools handle all cryptographic operations (X25519 and AES-256-GCM) automatically. Attempting manual implementation will introduce vulnerabilities and compatibility issues.
Fix: Always use the provided MCP tools like `download_transfer` for file operations. Trust the built-in cryptography.
breaking This package is in an early development stage (version 0.2.22), meaning breaking changes may occur frequently, even in minor versions. Always consult the official documentation before upgrading.
Fix: Regularly check the official documentation at `docs.agent-drop.com` for release notes and migration guides before updating to new versions.
gotcha Requires Node.js version 18.0.0 or higher. Running with older Node.js versions may lead to unexpected errors or silent failures.
Fix: Ensure your Node.js environment is updated to version 18.0.0 or later. Use `nvm` or similar tools to manage Node.js versions if needed.
gotcha The server automatically fetches agent profiles and updates every 5 minutes from `GET /v1/agents/me`. Ensure your AgentDrop API key and agent IDs (`AGENTDROP_API_KEY`, `AGENTDROP_AGENT_ID`, `AGENTDROP_AGENT_UUID`) are correctly configured and have the necessary permissions.
Fix: Verify that `AGENTDROP_API_KEY`, `AGENTDROP_AGENT_ID`, and `AGENTDROP_AGENT_UUID` environment variables are correctly set and correspond to an active AgentDrop agent with appropriate API access.

Install

npm install agentdrop-mcp-server npm
yarn add agentdrop-mcp-server yarn
pnpm add agentdrop-mcp-server pnpm

Imports

AgentDropMCPServer
```
import { AgentDropMCPServer } from 'agentdrop-mcp-server'
```
While primarily used as a CLI tool, this represents the main programmatic entry point for embedded or extended usage. Typically, you'd configure and start the server using this class.
MCPServerConfig
```
import type { MCPServerConfig } from 'agentdrop-mcp-server'
```
TypeScript type for configuring the server when initializing `AgentDropMCPServer` programmatically. Useful for defining environment variables or other settings.
ToolDefinition
```
import type { ToolDefinition } from 'agentdrop-mcp-server'
```
TypeScript type representing the structure of a tool recognized by the MCP server. Useful for type-checking when developing custom tools or integrations.

Quickstart

Demonstrates how to install the `agentdrop-mcp-server` globally and how to configure an MCP client to launch it with necessary environment variables.

npm install -g agentdrop-mcp-server

# Configure your MCP client (e.g., Claude Code, Cursor) to use this server.
# This example shows a typical JSON configuration snippet for an MCP client.
# Replace placeholders with your actual AgentDrop API key and agent IDs.
# Ensure AGENTDROP_CONFIG_DIR points to a persistent directory for agent state.

console.log('Starting AgentDrop MCP Server via npx...');

// This command would be executed by your MCP client, not directly run by you.
// It sets environment variables for the server to pick up its configuration.
// In a real scenario, this would be part of your MCP client's configuration.

// Example of how an MCP client might invoke it:
// You would typically configure this in your IDE/client settings, not run it manually.
// This snippet demonstrates the required environment variables.
const AGENTDROP_API_KEY = process.env.AGENTDROP_API_KEY ?? 'agd_your_api_key_here';
const AGENTDROP_AGENT_ID = process.env.AGENTDROP_AGENT_ID ?? 'your-agent-id-here';
const AGENTDROP_AGENT_UUID = process.env.AGENTDROP_AGENT_UUID ?? 'your-agent-uuid-here';
const AGENTDROP_CONFIG_DIR = process.env.AGENTDROP_CONFIG_DIR ?? '/path/to/.agentdrop';

console.log(`
{
  "mcpServers": {
    "agentdrop": {
      "command": "npx",
      "args": ["agentdrop-mcp-server"],
      "env": {
        "AGENTDROP_API_KEY": "${AGENTDROP_API_KEY}",
        "AGENTDROP_AGENT_ID": "${AGENTDROP_AGENT_ID}",
        "AGENTDROP_AGENT_UUID": "${AGENTDROP_AGENT_UUID}",
        "AGENTDROP_CONFIG_DIR": "${AGENTDROP_CONFIG_DIR}"
      }
    }
  }
}
`);

console.log('Ensure you have configured your MCP client to launch the server with these environment variables.');
console.log('Refer to docs.agent-drop.com for full setup instructions.');

view raw JSON →