fluidzero
Document intelligence platform for AI agents. Upload documents, define extraction schemas, run structured extractions, and search enterprise documents with full citations — from the fz CLI, a native MCP server, or the REST API.
fluidzero gives your AI agents the ability to read, understand, and cite enterprise documents — PDFs, images, and spreadsheets. Connect the way that fits your agent: install the fz CLI as an agent skill, drop the MCP server into Claude Desktop/Code/Cursor, or call the REST API directly.
Quick start (CLI) — four commands to your first extraction
pip install fluidzero-cli # or: brew install fluidzero/tap/fz
fz auth login # opens your browser once
fz init "My Project" # workspace + project + local config, no IDs to copy
fz extract specs.pdf --describe "compressive strength, mix design, curing period"
That last command uploads the file, waits for indexing, generates a JSON
Schema from your description, runs the extraction, and prints structured
JSON with citations. No UUIDs, no schema files, no polling loops.
`fz init` remembers the project in .fluidzero.toml, so every later command
in that directory just works — `fz extract more.pdf --schema <id>`,
`fz search "..."`, `fz documents list`.
Quick start (MCP server) — hosted, one command, no API key
The fastest path is our hosted server. One command, then a browser sign-in:
claude mcp add --transport http fluidzero https://mcp.fluidzero.ai/mcp
Or drop the block into any MCP client config:
{
"mcpServers": {
"fluidzero": {
"type": "http",
"url": "https://mcp.fluidzero.ai/mcp"
}
}
}
You sign in through your browser with WorkOS — no API key or secret to manage —
and every tool call runs as you, with your organization's permissions.
Self-hosted MCP (headless / M2M) — for CI and unattended agents
Prefer to run the server yourself, or need machine-to-machine auth with no
browser? Install the local server and let `fz mcp setup` mint an API key:
pip install fluidzero-mcp
fz mcp setup
`fz mcp setup` prints ready-to-paste config for Claude Code, Claude Desktop,
and Cursor. Manual form, if you already have credentials:
{
"mcpServers": {
"fluidzero": {
"command": "fz-mcp",
"env": {
"FZ_API_URL": "https://api-staging.fluidzero.ai",
"FZ_CLIENT_ID": "client_...",
"FZ_CLIENT_SECRET": "..."
}
}
}
}
Either way, the server exposes 50 tools prefixed `fluidzero_` (e.g. fluidzero_create_extraction, fluidzero_search, fluidzero_upload_document).
Agent skill setup (CLI)
The fz CLI is designed to be called by AI agents as a skill.
Example SKILL.md for Claude Code:
---
name: document-search
description: Search fluidzero documents with citations
allowed-tools: Bash(fz *)
---
Search documents using the fz CLI:
1. Run: fz search "$ARGUMENTS" -p <project-id> -o json
2. Parse the JSON response for citations
3. Present results with source references
Developer tools
- [fz CLI (Agent Skill)](https://fluidzero.ai/developers#quickstart): pip install fluidzero-cli — AVAILABLE. Agents call fz commands to manage workspaces, upload documents, define schemas, run extractions, and search with citations. - [MCP Server](https://fluidzero.ai/developers#mcp): Model Context Protocol — AVAILABLE. Hosted at https://mcp.fluidzero.ai/mcp with browser WorkOS OAuth (no API key), or self-host for headless M2M. 50 native tools for workspaces, documents, schemas, extractions, search, and webhooks. Works with Claude Desktop, Claude Code, Cursor, and any MCP client. - [REST API](https://fluidzero.ai/developers#api): AVAILABLE. RESTful endpoints for every platform operation. OAuth 2.0 authentication, camelCase JSON, and idempotent extractions. CLI commands (agent skill)
The golden path (after fz init, no -p needed anywhere):
# One command: upload -> index -> generate schema -> extract -> result
fz extract specs.pdf --describe "compressive strength, mix design, curing period"
# Reuse a saved schema — the latest version resolves automatically
fz extract more-specs.pdf --schema <schema-id>
# Extract from documents already in the project (no upload)
fz extract --schema <schema-id>
# Idempotent for pipelines: reusing --external-id returns the same run
fz extract batch.pdf --schema <schema-id> --external-id job-042
# Search with citations (JSON output for agent parsing)
fz search "concrete strength requirements" -o json
Building blocks, when you need step-by-step control:
fz documents upload *.pdf --wait # upload + index
fz schemas create "Concrete Specs" --file schema.json --message "v1"
fz schemas describe --text "..." # generate a schema, preview only
fz extractions create --schema <id> --external-id run-042 --wait
fz extractions result <extraction-id> -o json
fz workspaces list / fz projects list # explicit workspace/project management
REST API
# Exchange M2M credentials for an access token
curl -X POST https://api-staging.fluidzero.ai/oauth/token \
-d grant_type=client_credentials \
-d client_id=$CLIENT_ID \
-d client_secret=$CLIENT_SECRET
# List projects
curl https://api-staging.fluidzero.ai/api/projects \
-H "Authorization: Bearer $TOKEN"
# Create a schema (JSON Schema; every typed key needs a description)
curl -X POST https://api-staging.fluidzero.ai/api/projects/<project-id>/schemas \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"Concrete Specs","jsonSchema":{"type":"object","properties":{"compressiveStrength":{"type":"number","description":"Compressive strength in psi"},"mixDesign":{"type":"string","description":"Concrete mix design reference"}}}}'
# Start a headless extraction (v2 — returns 202, dispatches immediately)
# externalId makes retries idempotent: reusing it returns the existing run, never a duplicate
curl -X POST https://api-staging.fluidzero.ai/api/v2/projects/<project-id>/extractions \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"schemaVersionId":"<sv-id>","externalId":"run-042"}'
# Fetch the result once complete
curl https://api-staging.fluidzero.ai/api/v2/extractions/<extraction-id>/result \
-H "Authorization: Bearer $TOKEN"
# Search with citations
curl -X POST https://api-staging.fluidzero.ai/api/projects/<project-id>/search \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"query":"concrete strength requirements","includeCitations":true}'
Configuration
# ~/.config/fluidzero/config.toml (a .fluidzero.toml in the working directory overrides it)
# Merge order (later wins): built-in defaults < user config < project config < env vars (FZ_*) < CLI flags
[defaults]
api_url = "https://api-staging.fluidzero.ai"
project = "<project-id>"
output = "table" # table | json | jsonl | csv
[upload]
concurrency = 4
retry_attempts = 3
[runs]
poll_interval = 2
timeout = 600
Platform capabilities
- Workspaces & Projects: Organize documents into projects inside workspaces. Full CRUD from the CLI (fz workspaces, fz projects) and MCP.
- Document Upload: Client-direct multipart S3 uploads with parallel parts and automatic resume — files up to 5TB. Automatic versioning on same-name re-upload; PDF, image, and spreadsheet support.
- Schema Definition: JSON Schema definitions with immutable versioning. Author by hand, generate from natural language (fz schemas describe), or infer from a spreadsheet (fz schemas infer).
- Structured Extraction: Headless v2 extractions dispatch immediately and return structured JSON with per-field confidence and page-level citations. externalId keys make retries idempotent — safe for agents and pipelines.
- Search with Citations: Natural language search across your documents. Every result includes document name, page number, and a source excerpt.
- Webhooks: Create, test, and monitor webhook endpoints. HMAC-signed payloads, delivery history, and configurable retry logic.
- Authentication: Device flow for interactive use, M2M API keys for agents and CI, and OAuth 2.0 token exchange. Scoped permissions per credential.
Links
- [API Reference](https://fluidzero.ai/developers#api): REST endpoints, auth, and extraction lifecycle - [MCP Setup](https://fluidzero.ai/developers#mcp): Connect the MCP server to your agent - [Get Started](https://fluidzero.ai/resolve): Create an account and get your API key - [CLI on GitHub](https://github.com/fluidzero/fz-cli): Source code, issues, and contribution guide