Vremly MCP server

Gives an AI assistant access to the Vremly API over the Model Context Protocol — so it can look up your shoots, customers, media and invoices, and change them if you let it.

Full documentation: docs.vremly.com/guides/mcp

Install

Create an API key in the Vremly app under Settings → API Keys, then add this to your MCP host’s config:

{
  "mcpServers": {
    "vremly": {
      "command": "npx",
      "args": ["-y", "github:RelayDigital/vremly-mcp"],
      "env": {
        "VREMLY_API_KEY": "your-api-key"
      }
    }
  }
}

For Claude Code, that goes in .mcp.json in your project, or run:

claude mcp add vremly --env VREMLY_API_KEY=your-api-key \
  -- npx -y github:RelayDigital/vremly-mcp

There is nothing to clone or build — npx fetches the repo and compiles it on first run.

Configuration

Read-only sessions

VREMLY_MCP_READ_ONLY=1 also permits these reviewed POST operations, which need a request body to calculate a preview:

• /orders/prepare
• /agent-actions/booking/preview
• /agent-actions/rebook/{projectId}/preview
• /agent-actions/delivery/{projectId}/preview
• /agent-actions/followup/{projectId}/preview
• /agent-migrations/{migrationId}/reconciliation-preview
• /agent-actions/{booking|delivery|followup}/receipts/{receiptId}/reconciliation-preview

Other POST operations and all PUT/PATCH/DELETE operations are refused in this mode. These previews do not confirm bookings, charge payments, deliver media, send follow-up or commit migration changes. API-key scopes and organization/project authorization still apply to every permitted request.

Tools

Four tools expose the reviewed public integration surface:

Use capabilities → search → describe → request. Describing before calling avoids guessing request fields. Validated request bodies reject unknown fields with HTTP 400; endpoints without a published body schema may ignore unknown fields. The endpoint description identifies which behavior applies.

Permissions

Version 0.2.0 adds explicit read/write grants for evaluations, team, dispatch, reports, project conversations, scheduling, training, inventory, permitted settings, payroll, workflow catalogs and saved views. For example, EVALUATIONS_WRITE allows reviewed evaluation reads and writes while retaining all organization role and project authorization checks. It grants no other domain. Existing READ/WRITE credentials do not gain these capabilities. Create a new key with the needed grants; updating the local package grants nothing. Hosted connections require explicit reauthorization to add grants.

What the assistant may do is decided by the key and enforced server-side on every request — not by this process.

A key belongs to one organization and the server derives the organization from it, so the assistant can never reach another organization’s data.

No key can move money, at any scope, ADMIN included. The assistant cannot charge a card, issue a refund or take a card-reader payment; the server refuses those routes to every key, and they are not in the bundled openapi.json. To get paid it sends the customer a payment link (POST /invoices/{id}/send-payment-link). If it cancels a job that is already paid, the job is cancelled, the invoice stays paid, and the business gets an email to issue the refund in Vremly. It never charges a cancellation fee.

Give it a READ key unless it needs to write. That guarantee holds even if the assistant is prompt-injected by something it reads. VREMLY_MCP_READ_ONLY=1 is a convenience, not a security boundary — anything able to set that variable could also unset it.

Requests are rate limited per key. Each key has its own per-minute budget, set when it was created (120 by default, 10 to 1000 allowed), counted across every endpoint. Some endpoints add their own cap, with burst limits of 3 per second and 20 per 10 seconds. A 429 names the limit hit; this server returns the Retry-After-* and X-RateLimit-* headers in a rateLimit object beside the body. See Rate Limits.

Development

npm install
npm run build
npm run typecheck

prepare runs build, which is what lets npx install this straight from GitHub — dist/ is deliberately not committed.

This repository is a published mirror. The source of truth is apps/mcp-server in the Vremly monorepo, and openapi.json is generated from the backend rather than written by hand. Send changes there; edits made directly here will be overwritten by the next sync.