Hutch

Put every AI agent on the same data.
Self-host a structured workspace that Claude Code, Codex, Cursor, and other MCP clients can read and update together.

What is Hutch?

Hutch Core is a headless, single-user MCP server that gives every agent you run the same durable, structured data. Connect Claude Code, Codex, Cursor, VS Code, or another MCP client and they can store, query, and update shared collections of records across sessions.

Collections use schema-optional Postgres JSONB with full-text search, optional validation, and view definitions. There is no dashboard, no login screen, and no OAuth ceremony — just an MCP endpoint and a Postgres database you control.

This repo is the OSS engine. If you want people and agents working from the same visual workspace, Hutch Cloud adds web views, published pages, social login, and organization sharing. See Core vs Cloud below.

What can you use it for?

• Store and share structured data. Keep research, customer records, product data, and working context where every connected agent can find and update them.
• Run repeatable playbooks. Store the instructions, steps, inputs, outputs, and current status for work that needs to survive beyond one chat.
• Hand work between agents. Let one agent collect records, another process them, and a third report on the result without copying data between tools.
• Keep useful work across sessions. Decisions, backlogs, and open threads remain queryable after the context window closes.

Collections auto-create on the first write. Start with “save this to Hutch,” then query the same records from any connected agent.

Quick Start

Note: Full documentation lives at hutchdb.com.

1. Clone and boot (Docker):

   git clone https://github.com/ExpeditedProjects/hutchdb
   cd hutchdb
   docker compose up
   

   Core migrates the database and boots on port 3000. The singleton user and personal org are inserted lazily on the first request — there is no seed step.

2. Lock it down (optional but recommended off-localhost) — require a bearer token on every MCP call by setting an API key before booting:

   export HUTCH_API_KEY="$(openssl rand -hex 32)"
   

   If unset, all requests are trusted — fine for localhost, not fine for a public host.

3. Connect your agent. For Claude Code, add to your MCP config:

   {
     "mcpServers": {
       "hutch": {
         "type": "http",
         "url": "http://localhost:3000/api/mcp",
         "headers": {
           "Authorization": "Bearer YOUR_HUTCH_API_KEY"
         }
       }
     }
   }
   

   Cursor, Codex, and VS Code accept the same HTTP MCP server shape — same url, same bearer header.

4. Use it. Collections auto-create on first write — there is no setup step. Just talk to your agent:

   "Save these launch tasks to Hutch." "What did we store about the pricing research last week?" "Query the bug-reports collection for anything mentioning timeouts."

5. Verify the endpoint (optional):

   curl -X POST http://localhost:3000/api/mcp \
     -H "Authorization: Bearer $HUTCH_API_KEY" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
   

   You should see the hutch_* tool list (collections, records, schema, views).

git clone https://github.com/ExpeditedProjects/hutchdb
cd hutchdb
npm install
cp .env.local.example .env.local
# Required: HUTCH_DATABASE_URL
# Optional: HUTCH_API_KEY
npm run db:migrate
npm run dev

Example

A typical session with Claude Code connected to a local Core instance:

You:    Save each of these customer interviews as a record — tag the ones
        that mention pricing.

Agent:  Stored 9 records in `customer-interviews`, 4 tagged "pricing".

You:    (a week later) Which interviewees complained about onboarding?

Agent:  Querying `customer-interviews`... 3 records match: Dana R.,
        Marcus T., and the anonymous Feb 12 call.

Records are arbitrary JSON in Postgres JSONB — queryable via containment filters, Mongo-style operators ($gt, $in, $exists, $contains, …), and full-text search, with optional schemas when you want structure enforced. Collections export and import as CSV or JSON when data needs to move.

Hutch Core vs Hutch Cloud

Core is intentionally small. If you want the product layer, run Hutch Cloud — or fork Core and build your own.

claude.ai requires OAuth. Core ships no OAuth authorization server, so adding a Core instance to claude.ai (web) won't work out of the box. Claude Code, Cursor, Codex, and VS Code all accept a static bearer token and work fine.

Architecture

• Next.js App Router — one static landing page, one MCP route (/api/mcp), one REST seed route (/api/v1/collections). Everything else is deleted.
• Drizzle + Postgres — records stored as JSONB, queried via containment operators and full-text search.
• MCP server — collection tools (including per-collection stats), record tools (store/query/search/update/delete/status/transform plus CSV/JSON export and import), schema tools (describe/infer/update), and view tools. Queries support filter operators ($gt/$gte/$lt/$lte/$ne/$in/$nin/$exists/$contains), field projection, and count/min/max/distinct/sum/avg aggregations.
• Auth seam (src/lib/auth/seam.ts) — the only place auth lives: bearer-key check when HUTCH_API_KEY is set, singleton context otherwise.
• Singleton bootstrap (src/lib/auth/singleton.ts) — one user, one personal org, created lazily on first request.

Contributing

• Found a bug? Open an issue with repro steps.
• Want to improve Core? PRs welcome — contributors sign a CLA so the maintainer can dual-license into Hutch Cloud. See CONTRIBUTING.md and CLA.md.
• Feedback or ideas? Issues are the front door; tell us what you're building.

npm test          # vitest
npm run smoke     # end-to-end smoke test against a running instance:
                  #   SMOKE_BASE_URL=http://localhost:3000 npm run smoke
                  #   (keyed mode: add SMOKE_API_KEY=...)

License

AGPL v3.