Flatfile
Flatfile is a data exchange platform for collecting, validating, transforming, and managing structured data across collaborative workflows.
Verdict
Common use cases
- Audit failed import jobs from customer uploads
- Bulk-delete duplicate records flagged by validation
- Insert corrected rows after manual review
- Monitor async transformation job progress
- Retrieve sheet schemas before scripting fixes
Integration
- Vendor
- Flatfile
- Category
- developer-tools
- Auth
- API_KEY
- Tools
- 12
- Composio slug
flatfile
Tools
- Delete Recordsdestructive
Permanently delete one to 100 explicitly identified records from one Flatfile sheet. This action never performs an unfiltered delete. Flatfile hooks are disabled, so these deletions do not trigger hook-driven workflows.
- Get Job
Get detailed status, outcome, result, and diagnostic information for one Flatfile asynchronous job.
- Get Sheet
Get one sheet's field configuration and record counts before reading or writing records.
- Get Space
Get safe metadata for one Flatfile space without exposing transient access credentials or token-bearing guest links.
- Insert Records
Insert one or more rows into a Flatfile sheet using simple field-key to value objects. Returns Flatfile's success receipt and commit ID, not created record IDs. Use List Records separately when later work requires IDs; only attribute matche
- List Environments
List Flatfile environments visible to the connected environment secret key and return the IDs needed to find spaces.
- List Files
Discover import or export files and their processing status, optionally within a Flatfile space.
- List Jobs
Find asynchronous Flatfile jobs by environment, space, workbook, file, or parent job and inspect progress at a glance.
- List Records
Read one page of records from a Flatfile sheet, optionally filtering by validity, field, record ID, search value, or FFQL expression.
- List Spaces
Find Flatfile spaces by environment, text, namespace, archive state, or template status.
- List Workbooks
List workbooks, optionally within a space, with their nested sheets so an agent can continue to sheet and record tasks.
- Update Records
Update one or more existing Flatfile records by ID using simple field-key to value objects. Flatfile hooks are disabled, so these updates do not trigger hook-driven workflows.
Setup
Setup guide
- 11. Open your Switchy workspace settings and navigate to the Integrations tab. 2. Click 'Add MCP' and select Flatfile from the developer tools category. 3. Log into your Flatfile dashboard, go to Developer Settings, and generate a new secret key scoped to the environment you want Switchy to access. 4. Paste that secret key into the Switchy connection dialog and click Connect. 5. Switchy will verify the key by listing your environments; if it succeeds you'll see a green checkmark. 6. Inside any Project, type '@Flatfile list the spaces in environment env_abc123' to confirm the connection works. 7. The MCP returns space IDs, sheet configs, and job statuses—use those IDs in follow-up prompts to read records, insert rows, or delete bad data.
What teammates see: by default, memories from Flatfile are scoped to the Project (PROJECT visibility) - you can mark any memory PRIVATE or share it ORG-wide.
Works well with
Top models
Compatibility data appears once enough Projects have used this MCP together with a given model.
How Switchy teams use it
Starter prompts
List Recent Import Jobs
@Flatfile list the most recent jobs in space sp_xyz789 and show me their status and any error messages
Inspect Sheet Schema
@Flatfile get the sheet configuration for sheet sh_contacts456 and list every field with its type and constraints
Delete Flagged Records
@Flatfile delete records rec_001, rec_002, rec_003 from sheet sh_contacts456 and confirm the commit ID
Insert Cleaned Rows
@Flatfile insert these three records into sheet sh_contacts456: [{"email":"alice@example.com","name":"Alice"},{"email":"bob@example.com","name":"Bob"},{"email":"carol@example.com","name":"Carol"}]Check Job Outcome
@Flatfile get the full status and result for job job_transform_999 including any error logs or warnings
Example outputs
Illustrative - representative of the model's voice and quality, not literal recordings.
@flatfile list all sheets in space spa_abc123 and show me the field configuration for the contacts sheet
The space contains three sheets: contacts, companies, and deals. The contacts sheet has 847 records and defines 12 fields: firstName (text, required), lastName (text, required), email (text, unique), phone (text), company (reference to companies sheet), status (enum: active|inactive|prospect), tags (text array), createdAt (date), and four custom fields. Two validation hooks are configured. This illustrative example shows how Flatfile organizes imported data into typed, validated sheets within a workspace.
Demonstrates read-only inspection of Flatfile's schema and record counts. Requires a valid space ID from your account. Use this before writing records to understand field keys and validation rules. The Get Space and Get Sheet tools work together to map your data structure without modifying anything.
@flatfile insert 3 new contact records into sheet shd_xyz789 with names, emails, and status set to prospect
Successfully inserted 3 records into the contacts sheet. Flatfile returned commit ID com_def456 confirming the write operation completed. The insert bypassed validation hooks per the MCP's design, so downstream automation did not fire. To verify the records now exist or retrieve their Flatfile-assigned IDs, you must separately call List Records with appropriate filters. This example illustrates a bulk-insert workflow where you control timing of validation separately from data ingestion.
Showcases the Insert Records tool's ability to write multiple rows in one call. Returns a commit receipt, not the created record IDs—plan a follow-up List Records call if you need those IDs. Hooks are disabled during insert to prevent unintended side-effects; coordinate with your Flatfile workspace owner if validation must run immediately.
@flatfile check the status of import job job_ghi012 and summarize any errors that blocked completion
Job job_ghi012 (type: file-import, status: failed) processed 1,240 rows before halting. Flatfile reported 87 validation errors: 52 records had malformed email addresses in the email field, 23 records referenced non-existent company IDs, and 12 records exceeded the 255-character limit on the notes field. The job's outcome object includes row-level error details. This illustrative response shows how asynchronous jobs surface data-quality issues that must be resolved before re-importing.
Highlights the Get Job tool's diagnostic value when imports or exports fail. Flatfile jobs run asynchronously, so polling job status is essential for long-running operations. The error breakdown helps you fix source data before retrying. Combine this with List Jobs to track multiple concurrent imports across environments.
Use-case deep-dives
When Flatfile wins for new-customer CSV imports
A 6-person B2B SaaS team needs to onboard enterprise customers who send contact lists as Excel files with inconsistent column names and formatting. Flatfile is the right call here because the 12-tool MCP lets your AI agent validate schemas, insert cleaned records, and poll job status without writing a custom parser. The Get Sheet and Insert Records tools handle the heavy lifting while your team stays in Switchy to troubleshoot edge cases. The trade-off: if your onboarding volume is under 10 customers per month, a simpler webhook-to-Airtable flow might be faster to set up. Above that threshold, Flatfile's schema enforcement and job tracking pay off. Connect this MCP when your support team is spending more than 2 hours per week cleaning customer uploads.
When this MCP handles one-time data migrations
A 3-person product team needs to backfill 18 months of Mixpanel events into a new warehouse schema after switching analytics vendors. Flatfile works well for this because the List Jobs and Get Job tools let your AI agent monitor long-running imports without blocking other work in Switchy. You can stage the CSV export in a Flatfile space, validate field mappings with Get Sheet, then kick off the insert and check back in 20 minutes. The limit: Flatfile is overkill if your backfill is under 50,000 rows or you already have a working ETL pipeline. Use this MCP when the migration is large enough to need progress tracking but not so routine that you want to build a dedicated script. Best fit is one-time or quarterly data reconciliation tasks.
When Flatfile fits recurring ops workflows
A 10-person sales ops team updates territory assignments every Monday by uploading a CSV from Salesforce, validating zip codes, and pushing clean records to HubSpot. Flatfile is a strong match because the Delete Records and Insert Records tools let your AI agent handle the full replace-and-reload cycle in one Switchy conversation. The List Files tool surfaces any stuck uploads from the previous week. The catch: if your territory logic changes often, Flatfile's schema validation becomes a maintenance tax—you'll spend time tweaking field configs instead of just running the import. This MCP shines when your data shape is stable and the volume is 500 to 50,000 rows per run. Connect it when your ops team is manually spot-checking uploads in Google Sheets today.
Frequently asked
What does the Flatfile MCP do in Switchy?
It lets your AI agents read, write, and delete records in Flatfile sheets, check job status, and list environments or files. Agents can insert rows, fetch sheet schemas, and inspect space metadata without exposing guest links. Use it when you need programmatic control over data imports, transformations, or exports that live in Flatfile workbooks.
Do I need admin access to connect Flatfile?
You need an environment-scoped secret key from Flatfile, which typically requires admin or developer permissions in your Flatfile account. The key determines which environments and spaces the MCP can see. If you only have guest access to a single space, you won't be able to generate the secret key this integration requires.
Can the MCP trigger Flatfile hooks when deleting records?
No. The Delete Records tool explicitly disables Flatfile hooks, so deletions won't fire any custom logic you've configured. If you need hook execution, delete records through Flatfile's UI or a different API method. This design choice prevents accidental cascades when agents batch-delete rows during cleanup tasks.
How does this compare to calling Flatfile's REST API directly?
The MCP wraps Flatfile's API into 12 focused tools that agents can call without writing HTTP boilerplate. You trade flexibility for simplicity: the MCP won't expose every endpoint, but it handles auth, pagination hints, and error messages in a format agents understand. Use the raw API if you need features outside these 12 tools.
Who on the team should connect the Flatfile MCP?
Whoever manages your Flatfile environments and can generate secret keys—usually a developer or data engineer. Once connected in Switchy, any team member with workspace access can ask agents to query or modify Flatfile data. The secret key's environment scope controls what the MCP can touch, so audit that before sharing the connection.