@layervai/qurl-mcp

⚠️ Renamed from @layerv/qurl-mcp in v0.4.0. The old package is deprecated and will not receive further updates. If you're using @layerv/qurl-mcp@0.3.x, swap the scope in your MCP client config — same binary, same API key, no other changes.

A qURL MCP Server that supports both local stdio mode and remote HTTP mode for creating, managing, resolving, and sharing secure access links.

Overview

qURL MCP exposes qURL capabilities to MCP clients, GPTs, ChatGPT, and other remote integrations.

It currently supports:

• creating, reading, updating, and deleting qURLs
• resolving access tokens
• managing qURL tokens and sessions
• uploading text or file content and generating qURLs
• serving public legal pages
• serving a configurable MP4 video playback page

Runtime Modes

Feature Map

qURL Management Tools

Upload Tools

upload_file_qurl is intentionally stdio-only. It can read any supported PDF/image that the local MCP process user can access, so agents should invoke it only for a path the user explicitly selected for sharing. Do not expose it to untrusted prompts or autonomous agents: prompt injection could otherwise select another readable PDF/image on the host. Run stdio under an OS account whose filesystem access is limited to intended shareable content. HTTP mode never registers this host-file tool. The byte/text tools are also available in stdio so local clients can share in-chat attachments without first materializing them at a known host path. Connector upload and qURL minting are separate operations. If minting fails after upload, the connector currently has no delete endpoint; the server logs the orphaned resource_id for operator cleanup and returns the mint failure. HTTP upload attempts remain bounded by the per-IP and per-credential MCP rate limits; stdio operators should separately constrain autonomous retry loops. Upload validation binds the declared media type to the filename plus format start/end markers; it is not a malware scanner or full PDF/image decoder. For polyglot resistance, a PDF's final %%EOF marker must be followed only by ASCII whitespace; producer output with other trailing bytes is rejected even if a permissive PDF reader would accept it. JPEG validation checks framing and terminal markers rather than decoding image segments. The authenticated connector must independently decode or otherwise fully validate content before storage when semantic media validity matters. It must also preserve the declared safe media type and serve downloads with X-Content-Type-Options: nosniff rather than inferring an executable type. There is intentionally no application-level path allowlist: symlinks and time-of-check/time-of-use races make a lexical prefix check a misleading security boundary. Use a dedicated OS account, container, or read-only mount whose readable files are already limited to the intended sharing directory. The final path component is opened with O_NOFOLLOW; intermediate directory symlinks retain normal filesystem behavior under this trusted-local-user boundary.

MCP Resources

MCP Prompts

Quick Start

1. Install Dependencies

npm install

For a local stdio-only source install, use npm install --omit=optional; this omits the AWS SDK. HTTP deployments using the DynamoDB credential quota must use the ordinary install so the optional SDK is packaged.

2. Build

npm run build

3. Start

Local stdio mode:

npm run start

Remote HTTP mode:

npm run start:http

MCP Client Example

If you want to use this server in stdio mode with a local MCP client:

{
  "mcpServers": {
    "qurl": {
      "command": "npx",
      "args": ["@layervai/qurl-mcp"],
      "env": { "QURL_API_KEY": "lv_live_xxx" }
    }
  }
}

Configuration Files

Copy the tracked examples to create local configuration files:

cp qurl-mcp.config.example.json qurl-mcp.config.json
cp qurl-mcp.http.example.json qurl-mcp.http.json

The local files are gitignored so credentials and machine-specific paths are not committed.

Their responsibilities are:

qurl-mcp.config.json Reference

Shared Core Settings

Shared settings have these environment overrides. Environment values take precedence over the shared config file. The process caches resolved shared settings but automatically invalidates that cache when the file metadata or any relevant environment value changes.