---
title: "Docs — Hutch"
description: "Connect Claude (or any MCP client) to Hutch, and what every tool does."
canonical: https://hutchdb.com/docs
---

# Documentation

Connect Claude (or any MCP client) to Hutch, and what every tool does.

## What Hutch Is

Hutch gives AI agents a place to keep structured data. Tell your agent to save something — bookmarks, contacts, research notes, job applications, anything — and it lands in a collection you can query, filter, and export later, from any conversation. Collections are schema-optional and auto-create on first write. Everything an agent saves also renders as real views (tables, kanban boards, galleries) on your [Hutch dashboard](https://app.hutchdb.com), so the humans on your team see the same data your agents work with.

## Connect from Claude

**Claude (web, desktop, and mobile):** go to *Customize → Connectors → + Add → Add custom connector* and enter:

```
https://app.hutchdb.com/api/mcp
```

Claude walks you through OAuth — sign in (or create an account) and approve access. You can grant **read-only** or **read and write**; a read-only connection only ever sees the seven read tools.

**Claude Code (CLI):**

```
claude mcp add --transport http --scope user hutch https://app.hutchdb.com/api/mcp
```

Then run `/mcp` in Claude Code, select hutch, and authenticate.

**Any other MCP client** (Cursor, VS Code, Codex, …): Hutch is a remote MCP server speaking Streamable HTTP with OAuth 2.1 (PKCE + dynamic client registration). Point the client at the URL above and complete the OAuth flow. Hutch serves both current MCP protocol revisions, including 2026-07-28.

## First Five Minutes

There is no setup step. Say something like:

- "Save these three bookmarks to Hutch" — a collection is created automatically and the records stored.
- "What data do I have in Hutch?" — lists your collections with record counts.
- "Show me bookmarks about Postgres added this month" — filters and full-text search.
- "Give me my contacts as a CSV" — exports the collection as a flat file.

Everything your agent stores is immediately visible (and editable) on your dashboard at [app.hutchdb.com](https://app.hutchdb.com).

## Tools — Reading Data

- **List Collections** (`hutch_list_collections`) — every collection with id, name, slug, description, unique key, and record count.
- **Get Collection** (`hutch_get_collection`) — one collection's metadata and settings.
- **Describe Collection** (`hutch_describe_collection`) — field names, inferred types, sample values, and fill frequency.
- **Query Records** (`hutch_query_records`) — filters, full-text search, sorting, pagination, field projection, and aggregations (count, min, max, distinct, sum, avg, grouping, time buckets).
- **Search Records** (`hutch_search`) — full-text search across every collection at once.
- **Collection Stats** (`hutch_collection_stats`) — record counts, status breakdown, storage size, and exact per-field fill rates.
- **Export Records** (`hutch_export_records`) — a collection as JSON or CSV, honoring the same filters as queries.

## Tools — Writing Data

- **Store Records** (`hutch_store_records`) — write one or many records; the collection auto-creates if new.
- **Import Records** (`hutch_import_records`) — bulk-load CSV or JSON text (header row required for CSV; exports round-trip cleanly).
- **Update Record** / **Delete Record** — single-record edits by id.
- **Set Record Status** — active, pending, flagged, or archived.
- **Transform Records** (`hutch_transform_records`) — bulk rename, remove, or set fields across a collection.
- **Update Collection** — name, description, unique key for dedup, published flag.
- **Delete Collection** — removes a collection and its records (requires confirmation).
- **Infer Schema** / **Update Schema** — detect field types from data, or set them explicitly.
- **Create View** (`hutch_create_view`) — save a table, kanban, or gallery configuration on a collection.

## Filters

Query filters accept exact matches (`{"status": "active"}`) and Mongo-style operators per field:

- `$gt $gte $lt $lte` — comparisons (numbers numerically; strings, including ISO dates, lexicographically)
- `$ne` — not equal (also matches records missing the field)
- `$in / $nin` — value in / not in a list
- `$exists` — field present or absent
- `$contains` — case-insensitive substring match

Example: `{"price": {"$gte": 10, "$lt": 100}, "status": {"$in": ["active", "pending"]}}`

## Deduplication

Set a `unique_key` on a collection (for example `["url"]` or `["email", "date"]`) and every store or import honors `on_conflict`: **replace** (default), **merge**, **skip**, or **error**. Agents can re-run pipelines without creating duplicates.

## Limits

- Records: up to 1 MB each
- Imports: up to 10 MB or 10,000 records per call
- Exports: up to 10,000 records per call (a `truncated` flag tells you when there's more)
- Storage quota per the [plan](https://hutchdb.com/pricing) your organization is on

## Self-Hosting

The Hutch engine is open source (AGPL v3) and self-hostable — a headless MCP server backed by Postgres. See [github.com/ExpeditedProjects/hutchdb](https://github.com/ExpeditedProjects/hutchdb).

## Support

Questions or trouble connecting? Email [mike@expeditedsecurity.com](mailto:mike@expeditedsecurity.com).