Skip to content
Back to

MCP

Fontana Files exposes a first-party Model Context Protocol server on your tenant origin at /_fontana-files/mcp (Streamable HTTP). Clients work with namespaces: named git-backed file trees with viewer, editor, and admin grants.

This MCP port is for operators and external clients (Cursor, ChatGPT). It is text-only; binary and large files use the HTTP API on the same /_fontana-files prefix.

File System in Flow

Section titled “File System in Flow”

In Flow, open File System (/files, also linked from Admin → File System) to create namespaces, set grants, and browse files in a left-hand explorer. Every signed-in person can open it: the explorer lists the namespaces you hold a grant on, and what you can change follows your grant level. A files administrator sees every namespace.

One namespace holds everything it owns. Its tags say what it holds: skills for skills, agents for agents, and kg for Knowledge Graph documents, and a shared namespace carries every tag it needs. Inside a namespace, any folder that holds a SKILL.md is a skill and any folder that holds an AGENT.md is an agent (both names matched in any letter case), at any depth. New skills go under skills/ and new agents under agents/, and an id is the namespace plus the folder path, for example system/skills/email or finance/agents/nav-analyst.

The explorer lists namespaces alphabetically, each with its tags as small chips after it. Add ?type=agent, ?type=skill or ?type=kg to the address to list only namespaces with that tag. AI → Skills, AI → Agent packages and KG Studio embed the same explorer with their type fixed. The cog in the explorer header opens the explorer settings:

Setting What it does
Show hidden files Shows names that start with a period, and the paths a namespace’s .fontanaconfig.yaml hides.
Show hidden namespaces With a type filter, also lists namespaces without that type’s tag.
Show Fontana namespaces Lists the namespaces Fontana ships, such as system.
Explorer view File shows every row as a file or folder. Simple, the default, groups agents, skills, workflows, and dashboards under headings and leaves a heading out when that kind is empty. A saved choice applies on every page that uses the explorer.

Files administrators also see Resync cache there, which rebuilds the derived skill and agent catalogs from the namespaces. A .gitignore you save is kept in the namespace history; files it matches stay in the namespace and are not added to that history. Namespace admins can edit grants from the namespace menu. Grant lists show people by name and email, and teams by name.

Click a file, folder, or namespace to open it in the content pane; clicking a folder or namespace also expands or collapses it. Once you have clicked an item, the arrow keys move through the explorer as in VS Code: up and down move between rows, right expands a folder or namespace and then steps into it, left collapses it or jumps to its parent, and Home and End go to the first and last row. Moving with the keys does not open anything; press Enter or Space to open the highlighted row. The breadcrumb above the pane shows where you are, and each step in it opens that folder or namespace. The page address carries what is open, so you can share a link to it and use back and forward.

The pane shows the tabs that fit, in this order: Preview, Parsed, Source, Graph, and History. Preview is the friendly view: a PDF, a Word document, an image, rendered markdown, a spreadsheet, audio, video, a minisite (an HTML page), and a csv or tsv in the table explorer. The table explorer runs filters, sorts, groups, counts and charts on the server, so a file with millions of rows opens as fast as a small one. Show rows is 1, 5, 10, 50, or all. The numbered sizes load one page. All scrolls the whole file and loads the rows on screen. A markdown file renders on Preview, including its frontmatter as a table, and uses Source for the raw file. Parsed is the markdown Fontana made from a document such as a PDF or a Word file, and only in a namespace tagged kg. Source edits text files and stays off binary files. Graph is the knowledge graph for a file in a namespace tagged kg. A skill’s SKILL.md in a namespace tagged skills opens with the same editor as AI → Skills: Preview is the skill form, Source is the whole file, and Details shows the skill’s activity. All three edit the same text, so a change in one shows in the others. An agent’s AGENT.md in a namespace tagged agents opens with the same editor as AI → Agents, and its schedules.json opens with the rendered schedules as Preview and the JSON as Source. When an agent file cannot be parsed, the pane shows the error and the agent keeps its last good version. In a namespace tagged kg, a folder adds Graph, Status, and Config, and the namespace itself adds Ontology Agent as well. Every namespace has a Config tab that opens on its Tags: click Knowledge Graph, Skills or Agents to add or remove that kind, if you can edit the namespace. Adding Knowledge Graph starts processing the namespace’s documents; removing it stops processing and keeps the graph, so adding it back resumes. Removing Skills takes the namespace’s skills out of the catalog, and removing Agents makes its agents unavailable, deletes their schedules and revokes their mail addresses; the files stay, and you are asked first. The skill and agent catalog follows a change within moments. When you open another file, folder, or namespace, the pane stays on the tab you last picked if the new item has it, and otherwise opens the item’s usual tab.

History lists versions of the open file, folder, or namespace, grouped by day, with who changed it and a highlighted comparison against the previous version. Spreadsheets show changed cells, workflows show the review maps, and other text shows a unified diff. A version that changed one file opens that comparison at once. Restore writes a new version of the file or of the folder, and is only offered on older versions. Anyone who can read the namespace can open History; Restore needs editor or admin.

A Workspace (a namespace tagged project) also has Create Restore Point on its explorer menu, on File System and on Workspaces, just above Delete namespace. Create Restore Point names the current workspace, and the prompt starts with a date and time you can edit. Restore Point appears on that same menu only when an earlier named point exists, and lists those points, not the current one. Choosing a point compares the current workspace to that Restore Point in the pane, with the same highlighted views as History. Restore on that compare returns the workspace to that point and discards versions after it. A file that existed at that point no longer shows as deleted. A workflow on the canvas no longer shows a run from after that point. You need editor or admin to create or restore. History Restore still writes a new version; it does not discard later versions.

HTML pages, which Fontana calls minisites, render in a closed-off frame: files from the same namespace and secure https images, stylesheets, and fonts load, and links do not open. The amber icon beside the tabs opens About this preview, which lists any file that could not load and why. The page’s own scripts run; scripts from the web stay off until you turn on Allow external scripts there, and no script can reach Fontana or your account. The table explorer on Preview saves its views to .fontana/explorer/<path>.json in the same namespace, and editing cell values stays in Source. Saving needs editor or admin access. When sessions are waiting for review, an inbox icon beside the tabs links to them.

Namespace configuration

Section titled “Namespace configuration”

A namespace can carry a .fontanaconfig.yaml file at its root to configure itself. Every key is optional, and a namespace without the file works as described above. A new Workspace starts with a commented copy of this file:

defaults:
  workflows: workflows   # New workflow creates here
  agents: agents         # New agent creates here
  skills: skills         # New skill creates here
  tables: tables         # Unused. A table is a Save File on a workflow.
  input: data/in         # File Input uploads land here
  output: data/out       # New Save File nodes write here


hidden: []               # gitignore-style patterns, such as "*.bak" or "archive/"


# Workspaces only. Leave these out to keep today's explorer and welcome.
# ui:
#   explorer: closed
#   landing:
#     path: workflows/example.wf.json
#     view: exceptions

When you can edit a namespace, its add menu leads with New Workflow and New Dashboard, then New File, New folder, Upload files, and Upload folder. New Workflow creates in the folder defaults.workflows names, or in workflows when that key is absent. New Dashboard, Upload files, and Upload folder write into the folder whose menu you opened. In Simple view, the workflows, agents, skills, and dashboards headings each have their own add control. Those create in the folder defaults names for that kind. Without a setting, workflows and dashboards from a heading go to workflows, agents to agents/, and skills to skills/. Creating an agent or a skill adds that kind’s tag to the namespace. In a workflow, a new Save File node starts with the output folder, and File Input uploads and pastes go to the input folder.

In Simple view, View as on a workflow tile opens that workflow as a table, the canvas, exceptions, source, the graph, or history. The table is a Save File node on the workflow. One Save File is the table. When the workflow has several Save Files, mark each table on the Save File tab. One marked node is the default a tile click opens. The folder and file name are where the run writes.

hidden takes the same patterns as a .gitignore. Matching files and folders leave the explorer and the file pickers until you turn on Show hidden files. Hiding only changes what you see: the files stay in the namespace and its history, and .gitignore still decides what is committed.

Set kg.disabled to true when this namespace should stay out of Knowledge Graph ingestion. The Knowledge Graph tag stays on the namespace. Workspaces hides the graph tabs, and search leaves the namespace out. A graph that was already built stays. Leave kg out and ingestion stays on. The only known setting under kg is disabled.

On a Workspace, ui sets what you see when you enter it. ui.explorer is open or closed. closed hides the left-hand explorer for that workspace; you can still open it, and other workspaces keep their usual width. ui.landing names a file to open instead of the welcome: path is the file in the namespace, and view is optional (canvas, exceptions, analysis, json, inputs, outputs, dashboard). A typical operations workspace closes the explorer and opens Exception Management:

ui:
  explorer: closed
  landing:
    path: workflows/cash.wf.json
    view: exceptions

Landing runs when you open the workspace itself (the address has the namespace and no file). A link that already names a file stays on that file. The only known settings under ui are explorer and landing.

Folders are relative to the namespace root and cannot be the root itself, and the agents and skills folders cannot sit inside each other. Edit the file in the content pane with Show hidden files on; the explorer applies a saved change straight away. If the file has an unknown key or a wrong value, the namespace row shows a warning icon with the reason, and the namespace behaves as if it had no configuration until you fix the file.

Tool catalog

Section titled “Tool catalog”
Tool What it does
list_buckets List namespaces the caller can read (optional any-of tags filter)
create_bucket Create a namespace (the creating user becomes an admin)
delete_bucket Delete a namespace
get_perms Read the grant list (admin)
update_perms Replace the grant list
add_tag Add a display tag
remove_tag Remove a display tag
list_files Flat { path, size } subtree (folders are implicit)
get_file Read a UTF-8 file
query Query files: SQL, JSON, text, or grep (a path ending in / is a prefix)
put_file Write or replace a UTF-8 file
rename_file Rename a file inside a namespace
delete_file Delete a file

File paths are relative to the namespace file root. The namespace name and the file path are always separate arguments. bucket and namespace are the same name. A path may be the plain path (notes/a.txt) or the file id from a Knowledge Graph hit (file:notes/a.txt). Both name the same file. A grep hit returns path and fileId. Pass either back to get_file or query. In SQL the table name is the plain path, without the file: prefix.

Agents in Flow

Section titled “Agents in Flow”

The Files ability gives an agent the same tools inside Fontana, as mcp_ffs_list_files, mcp_ffs_get_file, mcp_ffs_put_file, mcp_ffs_query, and the rest. Each call runs as the person in the conversation and is checked against their namespace grants; a turn with no person cannot call them. Operators see the connection as Fontana Files under AI → Tools, with this page’s external client setup.

From a Knowledge Graph hit

Section titled “From a Knowledge Graph hit”

A Knowledge Graph result is a Fontana Files file. Every kg_search package, kg_open, kg_files, and kg_file result carries namespace, path, and fileId (file: plus path). Pass namespace and the same path or fileId, unchanged, to get_file or query here: bucket and namespace are the same name, and file:notes/a.txt and notes/a.txt are the same file. kg_file describes a file (size, mime, status, csv columns); reading it and every query, including a regex across a folder, happen here.

Access

Section titled “Access”

Every tool call authenticates as you (a personal access token or a signed-in browser session) and is checked against that namespace’s grants. A namespace you cannot access is invisible. Calls without valid credentials fail closed.

Tenant endpoints

Section titled “Tenant endpoints”

On your tenant Flow origin:

  • Health: https://<tenant>.<baseDomain>/_fontana-files/health (no auth)
  • MCP (Streamable HTTP): https://<tenant>.<baseDomain>/_fontana-files/mcp

External MCP clients (Cursor, ChatGPT)

Section titled “External MCP clients (Cursor, ChatGPT)”

Use a personal access token (PAT) to connect external MCP clients to your tenant’s public /_fontana-files/mcp endpoint. PATs authenticate as you; namespace grants follow your user, team, and tenant permissions.

Create a PAT under Admin → Personal access tokens and paste the full fnt_pat_… value into your client config.

Cursor

Section titled “Cursor”
{
  "mcpServers": {
    "fontana-files": {
      "url": "https://<tenant>.<baseDomain>/_fontana-files/mcp",
      "headers": {
        "Authorization": "Bearer fnt_pat_…"
      }
    }
  }
}

After editing MCP config, run Developer: Reload Window in Cursor (or fully quit and reopen).