Flatfile

The Flatfile MCP Server lets AI assistants interact directly with your Flatfile data by bridging AI capabilities to Flatfile’s rich data APIs. It enables you to view, query, and modify Sheets, Workbooks, Spaces, and more through natural prompts, making it easier to generate sheets, manage data, and perform complex actions from your preferred AI workflow.

How to use

You run the MCP server as a local stdio service and connect your MCP client (like Claude Desktop, Claude Code, or Cursor) to it. Start the server with the included command, then enable the specific tools you need so your AI assistant can perform tasks such as reading records, creating documents, updating sheets, and more. Use the enabled tools to drive data operations from natural language prompts, for example asking to generate a sheet from a description or update a record set across a workbook.

How to install

Prerequisites you need before installation:
- Node.js (recommended latest LTS)
- npm (comes with Node.js) or yarn
- Access to a Flatfile API key or a Flatfile Personal Access Token (PAT) to authorize API calls.

Install and run the MCP server as described in the setup steps below. The server is designed to be run via a package runner (like npm or npx) and is configured to enable a subset of tools you specify.

Step-by-step commands to set up the server locally:

1. Install dependencies (if required by your setup).
2. Start the MCP server using a runtime command (as shown in the configuration example).
3. Ensure your AI client can reach the MCP server and use the enabled tools.

Additional sections

Configuration and usage notes:

• You can enable only the tools you need by passing a comma-separated list with the --enabled-tools flag. If you omit it, all tools are enabled by default.
• Provide credentials via environment variables to authorize API calls. The common variables shown are FLATFILE_BEARER_TOKEN and FLATFILE_API_URL. The API URL may be set to a regional endpoint if you are operating outside the default region.
• When used with Claude Desktop, Claude Code, or Cursor, you add a dedicated MCP server configuration that points to the MCP runtime, including the token and URL as needed.

Notes on tools and capabilities:

• The MCP server exposes a wide range of endpoints for data operations such as getting records, updating records, creating documents, and managing spaces, workbooks, and environments. You can query data, generate new sheets from natural language, and perform administrative actions like archiving spaces or updating permissions.
• For best performance and security, restrict enabled tools to only those you truly need for your workflows.

Troubleshooting and tips

If you encounter authentication errors, verify that FLATFILE_BEARER_TOKEN is correct and that FLATFILE_API_URL points to the proper API endpoint. If a tool seems unavailable, double-check the --enabled-tools setting to ensure the desired tool names are listed exactly as supported.

Available tools

ackEvent

Acknowledge an event and return the event data to confirm handling.

ackJob

Acknowledge a job and return the job details.

archiveSpace

Archive a space by setting its archivedAt timestamp.

assignAgentRole

Assign a role to an agent.

bulkCreateActions

Create multiple actions in a batch.

bulkDeleteSpace

Delete multiple spaces by their IDs.

cancelJob

Cancel a running job and return its current state.

completeJob

Mark a job as complete and return the final job state.

createDocument

Add a new document to a space.

createWorkbook

Create a new workbook and add it to a space.

deleteSheet

Delete a specific sheet from a workbook.

getRecords

Retrieve records from a sheet within a workbook.

getSheet

Return a specific sheet from a workbook.

updateRecords

Update existing records in a sheet.

updateSheet

Update properties of a sheet.

createSpace

Create a new space from a given configuration.

listSpaces

List all spaces for an account or environment.

listWorkbooks

List all workbooks, filterable by account or space.