FileHutch
Sign in Start free
Documentation

Getting started

Agents and CLI

A project's configuration is a file. You, a CI job or a coding agent can diff it and apply it — and the same verbs are an MCP server, so an agent can set a project up end to end and show you the plan first.

Give an agent a read-only API key first (Dashboard → API keys → Access). It can inspect and plan; every write tool refuses it. Upgrade the key when you like the plan.

The file#

file_hutch.yml

uploads:
  avatars:   { types: [image/jpeg, image/png, image/webp], max_size: 10MB, visibility: public }
  documents: { types: [application/pdf], max_size: 25MB, visibility: private }
transforms:
  avatar: { width: 256, height: 256, fit: cover, format: auto }
environments: [staging]

Upload policies, transforms and environments. Unknown keys are errors, so a typo never plans as "nothing to do". Only what you declare is compared and written; the rest keeps its value. Storage connections, keys and webhooks carry secrets and stay out of the file.

Plan, then apply#

Terminal

gem install file_hutch
export FILE_HUTCH_API_KEY=fh_…

file_hutch export > file_hutch.yml   # start from what you have
file_hutch plan                      # what apply would change
file_hutch apply                     # make the project match
file_hutch apply --prune             # also delete what the file leaves out; asks first

Plan touches nothing and works with a read-only key. Apply runs each change through the same code the dashboard uses and reports every line; one failure (a plan limit, a bad size) does not stop the others. Nothing is deleted without --prune. Every change lands in the project's audit history.

Same thing over HTTP for any language: GET /api/v1/config, POST /api/v1/config/plan, and POST /api/v1/config/apply with {"config": …, "prune": false}. The TypeScript SDK has planConfig and applyConfig.

Point your agent at it#

Terminal

claude mcp add --transport http filehutch https://filehutch.com/mcp \
  --header "Authorization: Bearer fh_…"

Any MCP client works the same way: the URL, a bearer key, no install. The server tells the agent which project and environment it is looking at and whether its key can write.

Tools: inspect_project, get_config, plan_config, apply_config, create_upload, complete_upload, signed_url, create_api_key, manifest and a few more. There is no bulk delete and no billing tool.

Try this prompt:

Add private PDF uploads up to 25 MB and public avatar images to this app.
Avatars should get a 256×256 crop. Show me the plan before applying, then
wire the Rails model and upload a test file to prove it works.

Keep your options open#

Terminal

file_hutch manifest > files.jsonl   # every ready file with its object key

The manifest names the bucket and object key of every file. With it and your own credentials you can read your bytes without FileHutch. Moving between buckets is a button under Storage, and originals are never deleted.