Connect your AI assistant to Droplana

Droplana is a client portal: each client has one private portal where you send documents and they upload files back, with no account to create. This guide connects an AI assistant or automation tool to that account through Droplana's MCP server, and shows how to receive its webhooks. What an assistant can and cannot do once connected is on the integrations page. Everything here works on every plan, Free included.

What you need

• The address: https://mcp.droplana.com/mcp. It is the same for every business. Your sign-in or token decides which business the client sees, so the address does not change when you rename your business.
• A way in. Either sign in to Droplana and approve a consent screen, for a client that supports it, or create an access token and put it in the client's settings. Signing in is simpler where it works. A token suits clients that only take a header, and automation that runs without a person.

Which clients connect, and how

mcp-remote is a small open-source program, run with npx. It starts on your computer as a local server and forwards every request to Droplana over HTTPS. It needs Node.js 18 or newer. Nothing from Droplana is installed.

Connect by signing in

The client opens a Droplana sign-in page in your browser. Sign in the way you usually do, choose the business if you have more than one, and read the consent screen. It names the application and the address it will return to, and lists what it asks to do. When you approve, the client receives its own access, and you do not copy anything.

• Claude: open Connectors in Claude's settings, choose to add a custom connector, and paste https://mcp.droplana.com/mcp as its address.
• Claude Code: add the server, then run /mcp inside Claude Code and choose to authenticate.

claude mcp add --transport http droplana https://mcp.droplana.com/mcp

• mcp-remote, with no header: it registers itself and opens the sign-in page.

{
  "mcpServers": {
    "droplana": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "https://mcp.droplana.com/mcp", "--protocol", "auto"]
    }
  }
}

A connection made this way stays connected while the application keeps using it. It is listed under Account, Connected applications, and disconnecting it there ends its access at once. Only a business owner or team member can approve a connection. A client of yours cannot.

Connect with an access token

Open Account, API tokens in Droplana, choose what the token may do and when it expires (never, after 30 days, after 90 days or after 1 year), and create it. The token starts with dpl_ and is shown once, so copy it straight into the setup below. The client sends it in one header, Authorization: Bearer dpl_.... Droplana accepts it only from that header: a token in the address or in a cookie is refused.

Claude Code

One command. The default local scope keeps the server and the token in your own Claude Code settings, not in the project:

claude mcp add --transport http droplana https://mcp.droplana.com/mcp \
  --header "Authorization: Bearer dpl_your_token_here"

To share the server with a team in the project's .mcp.json, keep the token out of the file. Claude Code fills in ${DROPLANA_TOKEN} from each person's environment when it starts, and the single quotes stop your shell from replacing it first:

claude mcp add --scope project --transport http droplana https://mcp.droplana.com/mcp \
  --header 'Authorization: Bearer ${DROPLANA_TOKEN}'

Each person then sets DROPLANA_TOKEN to their own token. Check the connection with claude mcp list.

Cursor

In ~/.cursor/mcp.json for all projects, or .cursor/mcp.json for one. Cursor fills in ${env:NAME} from your environment, so the file holds no token:

{
  "mcpServers": {
    "droplana": {
      "url": "https://mcp.droplana.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:DROPLANA_TOKEN}"
      }
    }
  }
}

VS Code

In .vscode/mcp.json, or your user mcp.json (command MCP: Open User Configuration). VS Code asks for the token the first time the server starts, hides what you type and stores it itself:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "droplana-token",
      "description": "Droplana API token",
      "password": true
    }
  ],
  "servers": {
    "droplana": {
      "type": "http",
      "url": "https://mcp.droplana.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:droplana-token}"
      }
    }
  }
}

Claude Desktop and other stdio-only clients

Claude Desktop reads local servers from claude_desktop_config.json: on macOS in ~/Library/Application Support/Claude/, on Windows in %APPDATA%\Claude\. Restart Claude Desktop after you change it.

Keep the token in a header file that only you can read, for example ~/.droplana/headers.txt (on macOS or Linux, chmod 600 it), with one line:

Authorization: Bearer dpl_your_token_here

Then point mcp-remote at it, with the full path, because ~ is not expanded here:

{
  "mcpServers": {
    "droplana": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://mcp.droplana.com/mcp",
        "--header-file",
        "/Users/you/.droplana/headers.txt",
        "--protocol",
        "auto"
      ]
    }
  }
}

Keep --protocol auto. Droplana asks every request after the handshake to name the protocol version it speaks, and mcp-remote does not send it in its default mode. Without the flag the bridge connects, and then every tool call fails with Unsupported protocol version.

The header file keeps the token out of the config file, and out of the process list where other users of the same computer could read it. If the file cannot be read, mcp-remote stops with an error instead of connecting without the header.

If you prefer, put the token in the config's env block instead. mcp-remote fills in ${AUTH_HEADER} itself. Write Authorization:${AUTH_HEADER} with no space after the colon, because some clients split arguments on spaces:

{
  "mcpServers": {
    "droplana": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://mcp.droplana.com/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}",
        "--protocol",
        "auto"
      ],
      "env": {
        "AUTH_HEADER": "Bearer dpl_your_token_here"
      }
    }
  }
}

Any other client that takes command and args for a local server uses one of these two shapes.

Keep the token secret

A token works like a password for your business. Anyone who has it can do everything its permissions allow, without signing in, until it expires or you revoke it. Never commit it to a repository or paste it into a file other people see or sync, such as a shared .mcp.json, a screenshot or a support chat. Use the environment variable, input prompt or header file shown above. Make one token per client or computer, so you can revoke one without the others, and give each only the permissions it needs. If a token leaks, revoke it on Account, API tokens. It stops working at once.

Receive webhooks

The account owner adds an endpoint on Account, Webhooks. It must be an https address on the default port, on a public host. Droplana shows the endpoint's secret, starting with whsec_, once. Store it where your receiver can read it. Send test event on the same screen sends a ping to that endpoint only.

Each delivery is one POST with a JSON body and these headers:

• droplana-signature: the lowercase hex HMAC-SHA256 of the raw body, keyed with the secret
• droplana-delivery: the delivery id
• User-Agent: Droplana-Webhooks/1

One delivery carries up to 50 events:

{
  "deliveryId": "…",
  "events": [
    {
      "id": "…",
      "type": "document.uploaded",
      "createdAt": "…",
      "businessId": "…",
      "data": { "clientId": "…", "documentId": "…", "filename": "bank-statement-march.pdf", "sizeBytes": 482113, "uploadedBy": "client" }
    }
  ]
}

The event types are document.uploaded, comment.added, checklist_item.completed, checklist.completed, document.signed and client.created, plus ping from the test button. Ignore the types you do not need.

To handle a delivery:

1. Check the signature first, on the raw bytes you received, before parsing them. Compute the HMAC-SHA256 with your secret and compare it with droplana-signature in constant time. Reject the request if they differ.
2. Answer with any 2xx status within 10 seconds. Do slow work after you answer. Droplana reads only the status line.
3. Skip events you have already handled, by their id. A retried delivery is byte for byte the same request, and an event keeps its id across retries.

A delivery that fails is tried again after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 12 hours. After the last try the endpoint is turned off and the owner gets one email. Turn it back on from Account, Webhooks, and the events queued before it was turned off go out. To change the secret, delete the endpoint and add it again.

When it does not connect

• 401: the token is missing, mistyped, revoked or expired. Check that the header starts with Bearer followed by the whole dpl_... token.
• 403 with insufficient_scope: the token cannot use that tool. Create a token that has the permission.
• 429: too many calls in a short time. Wait the number of seconds in the Retry-After header, then try again.
• Unsupported protocol version: the mcp-remote bridge is running in its default mode. Add --protocol auto to its arguments. The connection itself succeeds without it, so this shows up as tools failing, not as a client that will not connect.
• mcp-remote stops at "Connecting": add --debug to its arguments and read the log it writes in ~/.mcp-auth/.

Questions