Veilfile

Docs

Agent setup

MCP

Veilfile hosts a Streamable HTTP MCP server at POST https://veilfile.com/mcp. It speaks JSON-RPC 2.0. Auth is your API key on every request:

Authorization: Bearer <key>

Most setups below read the key from VEILFILE_API_KEY. A key saved by veilfile login stays in its credentials file and does not set that variable. To set it, run veilfile key and export the key it prints. On Free, which allows one key, the approval page asks you to replace a key you already have, and the CLI and your agent then share the new one. Running veilfile login again can revoke that shared key, and your agent then needs a new one. veilfile logout never revokes a key also exported as VEILFILE_API_KEY; it deletes the local copy only. veilfile key prints the stored key but does not confirm it is still valid; run veilfile status for that.

Keys start with vlf_. The server exposes four tools: upload_artifact, create_upload_url, list_artifacts, and revoke_artifact.

upload_artifact takes the file as base64, which suits small files. For anything over a few MB (HAR files, log bundles, recordings), call create_upload_url and then curl --upload-file the raw bytes to the URL it returns. On a team, both tools take an optional visibility of only_me or team, honored when the administrator lets each person decide, and the upload's result says which one the file got. Failures come back as tool results with isError: true and a JSON {error, code} body.

Claude Code

claude mcp add --transport http veilfile https://veilfile.com/mcp \
  --header "Authorization: Bearer $VEILFILE_API_KEY"

Your shell expands the variable before Claude Code sees it.

Codex

codex mcp add veilfile --url https://veilfile.com/mcp --bearer-token-env-var VEILFILE_API_KEY

Or add this to ~/.codex/config.toml:

[mcp_servers.veilfile]
url = "https://veilfile.com/mcp"
bearer_token_env_var = "VEILFILE_API_KEY"

Antigravity

Add this to ~/.gemini/config/mcp_config.json, where Antigravity uses serverUrl:

{
  "mcpServers": {
    "veilfile": {
      "serverUrl": "https://veilfile.com/mcp",
      "headers": { "Authorization": "Bearer $VEILFILE_API_KEY" }
    }
  }
}

If Antigravity does not expand the variable, paste the key value directly and keep that file out of any repository.

Gemini CLI

Add this to ~/.gemini/settings.json, where Gemini CLI uses httpUrl for Streamable HTTP:

{
  "mcpServers": {
    "veilfile": {
      "httpUrl": "https://veilfile.com/mcp",
      "headers": { "Authorization": "Bearer $VEILFILE_API_KEY" }
    }
  }
}

Cursor

Add this to ~/.cursor/mcp.json, where Cursor expands ${env:...} so the raw key never sits in the file:

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

Or install in one click. The link uses the config above, and you paste your own key in Cursor.

Add to Cursor

VS Code

Add this to .vscode/mcp.json, where remote entries need "type": "http" and VS Code prompts for the key once and stores it:

{
  "servers": {
    "veilfile": {
      "type": "http",
      "url": "https://veilfile.com/mcp",
      "headers": { "Authorization": "Bearer ${input:veilfile_key}" }
    }
  },
  "inputs": [
    { "type": "promptString", "id": "veilfile_key", "description": "Veilfile API key", "password": true }
  ]
}

Windsurf

Add this to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "veilfile": {
      "serverUrl": "https://veilfile.com/mcp",
      "headers": { "Authorization": "Bearer ${env:VEILFILE_API_KEY}" }
    }
  }
}

Refresh from the Cascade panel after saving.

Other clients

Point any MCP client at https://veilfile.com/mcp over Streamable HTTP. The client must send Authorization: Bearer <key> on every request, with the key read from the VEILFILE_API_KEY environment variable or your secret manager. Header configuration differs per client. Check its docs.

pi and omp

pi and omp can use Veilfile through the veilfile command-line tool and a skill, with no MCP setup.

  1. Install the CLI with npm install -g veilfile or pip install veilfile, and install only one of the two. Then run veilfile login once in your own terminal.
  2. Install the skill:
mkdir -p ~/.agents/skills/veilfile
curl -fsSL https://veilfile.com/skills/veilfile/SKILL.md -o ~/.agents/skills/veilfile/SKILL.md

Both pi and omp load skills from ~/.agents/skills/. Start a new session and ask the agent to share a file it made. It runs veilfile push and gives you the link. The key stays in the CLI's credentials file, and the agent never sees it.

See Plans for how many uploads each plan allows and how long its links last.

Claude apps

The Claude apps sign in with OAuth, so there is no key to paste.

  1. Open Customize, then Connectors, then Add custom connector.
  2. Give the connector a name, such as Veilfile, and enter https://veilfile.com/mcp as its MCP server URL.
  3. If the dialog asks for an OAuth client, choose Register automatically, because Veilfile does not support Claude's published identity. If it shows Advanced settings instead, leave the OAuth client ID and secret blank.
  4. Sign in to Veilfile and approve the connection.

A Free Claude account can add one custom connector. On Team and Enterprise plans, an Owner adds the connector in Organization settings, under Connectors, and members then connect to it from Customize, then Connectors. Connectors added on the web or in Claude Desktop also work in the phone apps.

When a secret is flagged

Uploads are scanned for secret-shaped content. By default the scan warns and does not block: a flagged upload is stored and its link works. Pass on_secret: "reject" (recommended for agents) and a flagged file is refused and nothing is stored.

If secret_flags is non-empty in the upload response, do not share the link. Ask the user whether to keep or revoke the upload. Flagged responses also carry a warning field with this instruction.

To stop hosting a flagged file, check secret_flags in every upload response. Call revoke_artifact (or DELETE /api/v1/artifacts/<id>) when it is non-empty.

Use REST without MCP

Any agent that can make HTTP calls can use the REST API instead. See the API reference.