# Flatfile — how to use (mcp.ai)

Connect your Flatfile account and use 12 tools for developer tools straight from your AI agent. Connect with your own API key. Flatfile is a data exchange platform for collecting, validating, transforming, and managing structured data across collaborative workflows.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_flatfile?ms=1787291460000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `flatfile_delete_records`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/flatfile`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/flatfile/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/flatfile/delete/records` — 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 hoo
  - body: { sheet_id: string, record_ids: string[] }
- `POST https://api.mcp.ai/api/flatfile/get/job` — Get detailed status, outcome, result, and diagnostic information for one Flatfile asynchronous job.
  - body: { job_id: string }
- `POST https://api.mcp.ai/api/flatfile/get/sheet` — Get one sheet's field configuration and record counts before reading or writing records.
  - body: { sheet_id: string }
- `POST https://api.mcp.ai/api/flatfile/get/space` — Get safe metadata for one Flatfile space without exposing transient access credentials or token-bearing guest links.
  - body: { space_id: string }
- `POST https://api.mcp.ai/api/flatfile/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 
  - body: { records: object[], sheet_id: string }
- `POST https://api.mcp.ai/api/flatfile/list/environments` — List Flatfile environments visible to the connected environment secret key and return the IDs needed to find spaces.
  - body: { cursor?: string, page_size?: integer }
- `POST https://api.mcp.ai/api/flatfile/list/files` — Discover import or export files and their processing status, optionally within a Flatfile space.
  - body: { mode?: string, cursor?: string, space_id?: string, page_size?: integer }
- `POST https://api.mcp.ai/api/flatfile/list/jobs` — Find asynchronous Flatfile jobs by environment, space, workbook, file, or parent job and inspect progress at a glance.
  - body: { cursor?: string, source?: string, file_id?: string, space_id?: string, page_size?: integer, workbook_id?: string, parent_job_id?: string, environment_id?: string, sort_direction?: string, exclude_child_jobs?: boolean }
- `POST https://api.mcp.ai/api/flatfile/list/records` — Read one page of records from a Flatfile sheet, optionally filtering by validity, field, record ID, search value, or FFQL expression.
  - body: { query?: string, cursor?: string, fields?: string[], filter?: string, sheet_id: string, page_size?: integer, record_ids?: string[], filter_field?: string, search_field?: string, search_value?: string, include_links?: boolean, include_messages?: boolean }
- `POST https://api.mcp.ai/api/flatfile/list/spaces` — Find Flatfile spaces by environment, text, namespace, archive state, or template status.
  - body: { cursor?: string, search?: string, archived?: boolean, namespace?: string, page_size?: integer, environment_id?: string, is_app_template?: boolean }
- `POST https://api.mcp.ai/api/flatfile/list/workbooks` — List workbooks, optionally within a space, with their nested sheets so an agent can continue to sheet and record tasks.
  - body: { name?: string, label?: string, space_id?: string, namespace?: string, include_sheets?: boolean }
- `POST https://api.mcp.ai/api/flatfile/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.
  - body: { records: object[], sheet_id: string }

## Example prompts
- "What can I do in Flatfile?"
- "Show me a summary of my Flatfile account"

## More
- Page: https://mcp.ai/flatfile
- Agent spec (llms.txt): https://mcp.ai/flatfile/llms.txt
- Postman collection: https://mcp.ai/flatfile/postman.json