Gentic Files — Documentation

1. Getting Started

Sign Up & Get Your API Key

Before you can use Gentic Files, you need an API key to authenticate your requests.

1. Go to gentic.co/files and create an account.
2. Create an organization from your dashboard. API keys and billing are scoped to the organization.
3. Generate an API key and use it as a Bearer token in your MCP client.

2. Connecting to the MCP Server

The server is available at https://mcp.gentic.co/files. For Claude Code:

claude mcp add gentic-files \
  --transport http \
  https://mcp.gentic.co/files \
  --header "Authorization: Bearer YOUR_API_KEY"

For Claude Web and ChatGPT you can also connect via OAuth — no API key needed. See the connect section on the landing page for other MCP clients (n8n, OpenClaw).

3. Agent Skill

For the best results, pair the MCP server with the Gentic Files agent skill. The MCP server gives your agent tool access; the skill teaches it the optimal workflow order. Both the raw SKILL.md and a ready-to-upload .skill bundle are generated on demand from the live manifest, so they always reflect the current tools and pricing.

Add the skill directly via URL:

https://gentic.co/files/SKILL.md

Or upload a .skill bundle to Claude Managed Agents:

https://gentic.co/files/gentic-files.skill

Download this file and upload it wherever Claude Managed Agents asks for a .skill file. It's a zip bundle generated on demand from the latest SKILL.md.

4. When to Apply

• User says "save this as a file", "add this file", or names a path/filename to store an exact artifact (a transcript, a doc, a run-of-show).
• User says "add X as an agenda item" or "add this as prep for the pod" — drop it into a prep folder as a file.
• User wants a file back exactly as it was saved ("give me the transcript from episode 34", "pull up the run-of-show").
• User wants to grow a single doc over time — "add this topic to the episode-2 prep", "append this to the running notes" — rather than make a new file each time.
• User wants to find a saved file by meaning when they don't remember the exact path.
• User wants to organize artifacts into folders (path prefixes) or list what's in one.
• Reserve Brain capture for ambient / automatic capture of externally-originated sources (Slack threads, emails, reviews, web PDFs) — Files is for exact artifacts the user explicitly wants stored and returned verbatim.

5. Workflow

1. 1. Route save-a-file to Files, ambient capture to Brain

   Use Files when the user explicitly wants an artifact stored and returned exactly — "save this as a file", "add this transcript", "add X as prep for the pod", or any request that ends in them wanting the file back byte-for-byte. Reserve Brain's `wiki_stage_source` for ambient/automatic capture of externally-originated sources (a Slack thread, an email, a review, a web PDF the agent ingests on its own). The mental model: Files = canonical state, Brain = derived index, Wiki = synthesized curation. A `save_file` is never a `wiki_ingest` — they have different contracts and different homes.

2. 2. Save by path; the path is the identity

   `save_file` takes a path like `episode-2-prep/run-of-show.md` and the content as text/markdown. The path (normalized) is the file's logical identity — re-saving the same path replaces the whole file in place (new bytes, new version, stale index chunks retired) rather than creating a duplicate. To add to a file instead of overwriting it, reach for `append_file` (below). Paths are validated: traversal (`..`), control characters, and over-long names are rejected. Text and markdown first; binary is a phase-2 capability.

3. 3. Grow a running doc with append_file

   `append_file` adds new content to the end of an existing file — the caller sends only the new bytes, and everything already in the file is preserved exactly. That's the point: an append never rewrites prior content, so the verbatim guarantee holds even as a doc evolves. Use it to build up a single document over time instead of scattering one file per fragment — e.g. collect podcast topics into one `episode-2-prep.md` by appending each new topic as it comes in, rather than `topic-1.md`, `topic-2.md`. It's create-or-append: appending to a path that doesn't exist yet creates it, appending to one that does adds to the end. Append-to-end only — to change earlier content, read with `get_file`, edit, and `save_file` the whole thing back.

4. 4. Use folders as path prefixes

   There are no folder objects — a "folder" is just a shared path prefix like `episode-2-prep/`. Collect related artifacts by giving them a common prefix (drop articles and a transcript into `episode-2-prep/`, then build a `run-of-show.md` alongside them). `list_files` and `find_file` both scope to a prefix, so you can list or search within one folder without touching the rest of the org's files.

5. 5. Get back exact bytes with get_file

   `get_file` returns the precise UTF-8 content `save_file` stored — no LLM summary, no truncation. This is the read boundary: it looks the file up in the org's manifest, verifies ownership, then returns the stored bytes (or not-found for a missing or deleted file). When the user asks for "the transcript from episode 34", resolve the path (you may need `find_file` first) and hand back exactly what was saved.

6. 6. Find by meaning, then fetch verbatim

   `find_file` is retrieval-only — it runs a semantic search over the knowledge index filtered to your files (body + metadata: path, filename, tags, title) and joins the manifest to return matching file paths. It never synthesizes an answer and never calls Brain's query path; it tells you which file the user means. Follow it with `get_file` to return the actual content. A file that's saved but not yet indexed surfaces its index status rather than silently missing.

7. 7. Delete removes the file for real

   `delete_file` deletes the stored object, tombstones the manifest row, and un-indexes the file's knowledge chunks so it stops appearing in `find_file`. It's the clean way to retract a file the user no longer wants. List and find never return tombstoned files; a subsequent `get_file` on a deleted path returns not-found.

6. Tool Reference

6 tools, rendered live from the Gentic MCP manifest. Parameter tables come directly from each tool's JSON Schema.

7. Pricing

Pricing is pulled live from the Gentic MCP manifest. All prices are per call and deducted from your Gentic credits.

8. Notes

• All tools are organization-scoped — the auth context determines the org, and every read verifies per-org ownership against the manifest before touching storage. Files are never exposed at a public URL.
• Verbatim contract: `get_file` returns the exact UTF-8 bytes `save_file` stored — no synthesis, summarization, or truncation. Files is canonical state, distinct from Brain (derived index) and Wiki (synthesized curation).
• Identity is the normalized path. Re-saving the same path replaces content in place — new version, prior index chunks retired — so the store doesn't accumulate duplicates. An identical re-save is a no-op.
• `append_file` is a server-side, append-to-end-only, create-or-append operation: the caller sends only the new content and the prior bytes are preserved exactly. Editing earlier content means get_file → edit → save_file the whole file back.
• Saving indexes both the body and the metadata (path, filename, tags, title) into the shared knowledge layer, so a file can be found by an identifier that only appears in its path or tags.
• All Files tools are free; background vectorization of a saved file charges its own per-chunk meter on the shared `vectorize_content` index on completion — the same note as Brain.
• Text / markdown first; binary files are a phase-2 capability. Folders are path prefixes, not objects — `list_files` and `find_file` scope to a prefix.