The MCP tools

Every tool is named factorin_*. The prefix is deliberate: a model choosing between your library and the host app’s own features needs to tell them apart, and a bare word like “search” loses that contest every time.

There are two connector URLs, and the difference is which tools each serves.

• https://connect.factorin.com/mcp serves the library tools: reading and writing. It is the URL the Claude and ChatGPT directories list.
• https://connect.factorin.com/mcp/full serves the same tools plus cloud runs and triggers, and lets factorin_list and factorin_read reach a workspace. Add it as a custom connector, in place of the first, to start cloud runs from your AI app. They need a Cloud plan.

Three rules hold across both. No tool mixes a read with a write. Every write saves immediately as a new version, and earlier versions are kept. Nothing destroys content: factorin_archive hides a row rather than removing it. It is marked destructive so your AI app asks you before each one; at /mcp/full, so are starting and stopping a cloud run, which spend compute and can lose work in progress, and deleting a trigger.

One connection reaches every library the person is a member or guest of. A tool that takes an id already knows its library. A tool that does not takes a library slug, which can be left out when only one library is reachable.

Reading

factorin_list_libraries. List every library the person can reach, with the slug to pass as library to other tools and whether each can be written. Call it when a tool refuses for want of a library, or when the list given at connection time may be out of date.

factorin_list. List what is in a library as a tree: folders, skills, notes, prompts and attachments, every line with the id that addresses it. Narrow with kinds (note, prompt, attachment, skill), or with content_type, min_bytes and max_bytes to ask about attachments (“every image”, “anything over 5 MB”). Narrowing also drops folders holding nothing you asked for. At /mcp/full, pass workspace (a slug, from factorin_list_workspaces) to list a saved workspace version’s files instead, optionally with version and a prefix folder.

factorin_search. Search a library by content and by name. Matching lines come back with their id, the way grep would. A file whose name matches comes back too, which is the only way to find an attachment. Use it whenever you would otherwise guess at a name or assume something does not exist. Takes query (literal text, case-insensitive), and optionally folder_id, kinds, library and limit.

factorin_list_skills. List every skill with its description, its path, the size of its SKILL.md and the folder id that addresses it. Skills can sit at any depth, so this finds them all. Read one with factorin_read and follow it where it is. Skills are not installed into the client. The library stays the one copy.

factorin_read. Read a file or skill by id or by path. A path may be a library path (Prompts/Setup library.md), a bare file name, or a link exactly as written inside another file, relative ones included. Pass origin_id with a relative link so it anchors to the file it was written in. A note, prompt or skill file returns its payload, which is what factorin_write takes back. A skill returns its SKILL.md and the names of its files. An image returns as an image, any other attachment as base64, and anything over 8 MB as a short-lived download URL. At /mcp/full, with workspace (and optionally version), path is a file in a saved workspace version: the current version or a pending one, never someone’s unsaved draft.

Writing

factorin_create. Create a note, a prompt, a skill or a folder (the kind), at the library root or in a folder_id.

• A note is something to read.
• A prompt is an instruction to run later, and may carry input_schema and output_schema as JSON Schemas.
• A skill is a folder holding a SKILL.md manifest plus support files. Its name is normalized to kebab-case, like pdf-extraction, and it needs a description: what the skill does and when to use it, which is what a model reads when deciding to invoke it. The body is the manifest.
• A folder takes only a name. Pass the id it returns as folder_id to the create and write tools so output lands somewhere sensible rather than at the root.

What belongs to one kind is refused on the others, by name: only a prompt takes schemas, only a skill takes a description, and a folder takes no body.

factorin_write. Save a new version of an existing note, prompt or skill file. Send edits, a list of {old_text, new_text} replacements applied in order, each old_text matching exactly once, to change part of a file cheaply. Or send payload, the whole payload factorin_read returned with your changes, since anything left out is removed. Earlier versions are kept.

factorin_write_attachment. Create or replace a binary file: image, audio, PDF, archive, data file. For bytes already in context, send content_base64 (up to 8 MB). For a file on disk at any size, send byte_size to get an upload URL, PUT the file there, then call again with the upload_id to save it. The bytes never pass through the model’s context.

factorin_move. Rename a file, folder or skill, move it into a different folder, or both. A folder or skill moves with everything inside it.

factorin_archive. The library’s “delete”. The row leaves the tree, a folder or skill takes everything inside it, and nothing is destroyed. History is kept and the row can be restored from the web app.

Cloud runs

A cloud run is work done on FactorIn’s servers, not on your machine: a model of its own works on a prompt for a few minutes, with the library’s skills and the integrations connected to it, and writes its result to the library or to a new version of a workspace. These tools are served at /mcp/full only. They need the connection’s run grants, and a guest gets none of them.

factorin_list_integrations. List the integrations a library can hand a cloud run, each by key and name, whether it is connected and as which credential (never its id or secret), whether a cloud run can use it, and which of the library’s skills require it. Integrations are connected in the web app; the answer says where.

factorin_list_models. List the AI providers a library can run a cloud run on, each by key and name, with its credential names (the library’s default first) and its enabled models by id, name and tier, the default marked. Pass a model id as model when starting a cloud run, and a provider’s key and credential name in credentials to use a credential other than the library’s default. Name neither and the cloud run uses the library’s default.

factorin_list_workspaces. List the library’s workspaces, each a Git repository a cloud run can build in, with the versions a cloud run can start from: the current one, then any pending ones an earlier cloud run made that are not yet merged.

factorin_start_cloud_run. Start a cloud run in a home: the library path of the note, prompt or folder it lives in, made as a note if the path is new. Without a workspace, the home is also what it works on. What it does is a saved prompt or note (prompt_path), which brings its own skills, integrations and inputs, or the home’s own text, or prompt, which runs in place of either. Optionally give it:

• skills by path or name, and integrations by key. Those the prompt or a skill requires come without being named.
• model, a model id from factorin_list_models, and credentials, integration key to credential name, to run an integration or the AI provider on a credential other than the default. Without a model, it runs the library’s default for the prompt’s tier.
• inputs for the prompt’s declared inputs, and an output_schema its answer must match.
• A workspace to build in, with a version to start from, or a new_workspace. The result is then a new version of that workspace.

To continue a finished cloud run, send its id as continue_run in place of home, with a prompt or prompt_path saying what to do next. It runs as part of that cloud run, in its home and on the workspace version it made. Either way the tool returns at once with the cloud run’s id and a link to it. It spends the library’s compute and credit, and a library whose plan does not include cloud runs is told so.

factorin_get_cloud_run. By run_id, or by a home path for that home’s latest cloud run and the ids of earlier ones: a cloud run’s status and, once it has finished, its summary (or its output, when it was started with an output schema), the notes it wrote with their diffs, and for a workspace the new version, its changed files and its diff. wait holds the answer up to 25 seconds until the status changes, which saves polling.

factorin_stop_cloud_run. Stop a cloud run that is still working, such as one started by mistake. It stops a moment later, keeping what it can of the work in progress.

Triggers

A trigger is a saved cloud run with a schedule: it starts on a cron schedule as the person who made it, with no one opening the app. These tools are served at /mcp/full only. Triggers are rolling out library by library, and in a library that does not have them yet these tools say so. Any member can list a library’s triggers; creating, disabling and deleting one takes a library admin.

factorin_list_triggers. List a library’s triggers: each one’s id and name, whether it is enabled or why it was disabled, its cron schedule and time zone, its next three firings, the cloud run it starts in factorin_start_cloud_run’s argument names, and how its last firing went.

factorin_create_trigger. Create a trigger with a name, unique in the library, a home that already exists, and a schedule: a five-field cron expression, at most once an hour, and an optional IANA timezone, defaulting to the person’s own. It takes factorin_start_cloud_run’s other arguments too, except version and continue_run: each firing is a new cloud run, on the workspace’s current version when it names one. busy says what happens when a cloud run is still active in the home at a firing: queue, the default, starts it once that cloud run ends, and skip drops the firing. Every argument is checked the way starting the cloud run would check it, before anything is saved. It returns the trigger with its next three firings, for your AI app to confirm with you. There is no update: to change a trigger, delete it and create it again.

factorin_disable_trigger. Turn a trigger off by its id, so it stops starting cloud runs. It can be turned on again only in the web app.

factorin_delete_trigger. Delete a trigger and its firing log by its id. The cloud runs it already started are kept.

Tools a cloud run sees

A cloud run uses the library tools as /mcp/full serves them, workspaces included, but none of the cloud run or trigger tools above: a cloud run cannot start, follow or stop another, or schedule one. It sees four of its own that a person’s connection never does: read and write a scratchpad that belongs to that run, schedule a continuation so a long external job can be waited for without polling, and create a workspace to build in. They spend money or hold run state, so they are offered only to a credential that is a run.

Style the tools ask for

Write markdown prose as one line per paragraph. A display wraps it, and hard-wrapped lines are painful to edit later with edits. Line breaks belong only where they are content: code fences, tables and list items.

What a connection can and cannot do

• A member of a library on an active plan reads and writes, and on a Cloud plan starts cloud runs through /mcp/full.
• A member looking at a GitHub mirror, or at a library whose plan has lapsed, reads only. Nothing under a mirror is written locally; only the sync gets through.
• A guest under a grant reads one folder and everything under it, writes only in their own dropbox, and sees no version history and no cloud runs.
• A library past its first 7 days without a plan is readable and still exports whole.

Every rule is the same on every surface: the web app, the connector and the public API all ask the same questions of the same records.