# HutchDB

> HutchDB (Hutch) is a backend database for AI agents. Agents save their work as JSON records in collections over MCP, with no schema, SQL, or setup. People see the same records in the browser as tables, kanbans, calendars, and galleries.

Every agent connected to an account reads and writes the same collections, so one agent can pick up where another left off.

- Hosted MCP server: https://app.hutchdb.com/api/mcp
- Transport: remote streamable HTTP
- Auth: OAuth. The user signs in with GitHub or Google and approves access. Headless runtimes can use a Hutch API token instead.
- Open source core (AGPL), Postgres underneath, also reachable over REST. Self-hosting is free.

## When to use Hutch

Use Hutch when you produce structured records that the user or another agent will come back to. Best fits:

- Tasks and handoffs between agents: one agent queues the work, another claims it, and the user follows the status on a kanban.
- Leads and contacts gathered from research or outreach.
- Research results: companies, articles, sources, findings.
- Drafts waiting for review, such as posts, emails, or subject lines.
- Any list the user wants to see, filter, and edit as a table, kanban, calendar, or gallery.

Don't use Hutch for:

- Semantic retrieval. Hutch is not a vector database; it finds records with filters and full-text search, not embeddings.
- Your own prompts, system instructions, or agent config. Keep those where your agent loads them.
- Standalone files. Hutch is not a file store; a file belongs on a record that describes it.

## If you are an AI agent: connect Hutch

If your user asked you to set up Hutch, add it as a remote MCP server. Add it for the user account, not one project. Then start the OAuth login, or tell the user exactly what to click. Once connected, call hutch_list_collections to confirm it works.

The prompt a user would paste into you:

```
Connect Hutch (hutchdb.com) to this agent as an MCP server.

- URL: https://app.hutchdb.com/api/mcp
- Transport: remote streamable HTTP
- Auth: OAuth (no API key). I'll approve in the browser.

1. Add the server for my user account, not just this project, so it works everywhere.
2. Start the OAuth login, or tell me exactly what to click if you can't start it yourself.
3. Tell me if I need to restart or reload you. Then call hutch_list_collections to confirm it works.
```

## Per-client setup

These steps are written as the user would say them to you, so "me" means the user.

### Claude Code
Guide: https://hutchdb.com/claude-code
- Run: claude mcp add --transport http --scope user hutch https://app.hutchdb.com/api/mcp
- Then run claude mcp login hutch, or tell me to run /mcp and authenticate hutch.

### Codex
Guide: https://hutchdb.com/codex
- Run: codex mcp add hutch --url https://app.hutchdb.com/api/mcp (it detects OAuth and starts the login).
- If hutch is already configured, run codex mcp login hutch.

### OpenCode
Guide: https://hutchdb.com/opencode
- In ~/.config/opencode/opencode.json, add under "mcp": "hutch": {"type": "remote", "url": "https://app.hutchdb.com/api/mcp"}
- Then run opencode mcp auth hutch.

### OpenClaw
Guide: https://hutchdb.com/openclaw
- Run: openclaw mcp set hutch '{"url":"https://app.hutchdb.com/api/mcp","transport":"streamable-http","auth":"oauth"}'
- Then run openclaw mcp login hutch, and check it with openclaw mcp doctor hutch --probe.

### Claude Desktop
Guide: https://hutchdb.com/claude-desktop
- Open Customize > Connectors, then click + Add > Add custom connector. Name it "Hutch" and paste this URL: https://app.hutchdb.com/api/mcp
- Click Continue through the authentication settings, then Add. Click Connect, sign in with GitHub or Google, and approve.

### ChatGPT
Guide: https://hutchdb.com/chatgpt
- Go to Plugins (chatgpt.com/plugins), click +, then Add custom MCP server. Name it "Hutch" and paste this URL under Connection: https://app.hutchdb.com/api/mcp
- Set authentication to OAuth, check "I understand and want to continue", and click Create as a plugin. A browser window opens. Sign in with GitHub or Google and approve.

### Antigravity
Guide: https://hutchdb.com/antigravity
- In ~/.gemini/config/mcp_config.json, add under "mcpServers": "hutch": {"serverUrl": "https://app.hutchdb.com/api/mcp"} (Antigravity requires serverUrl, not url).
- You can't run the OAuth login yourself: tell me to open Agent settings > Customizations and click Authenticate next to hutch.

### Hermes
Guide: https://hutchdb.com/hermes
- In ~/.hermes/config.yaml, add under mcp_servers: hutch: {url: "https://app.hutchdb.com/api/mcp", auth: oauth}
- Then run hermes mcp login hutch. Tell me to run /reload-mcp in my session.

### Grok Bot
Guide: https://hutchdb.com/grokbot
- Send this to a Grok Bot:

  ```
  Add a custom MCP server named hutch at https://app.hutchdb.com/api/mcp using streamable HTTP.

  Once it’s connected, remember this for all future work: Hutch is our shared app database.
  - Save structured work to a Hutch collection, not a file or a chat message: tasks, leads, research, drafts, lists.
  - Reuse existing collections and field names. Only create a new collection for a new kind of work.
  - Before starting a task, check Hutch for records that already exist.
  - Give records a status (open, in progress, done, blocked), and put your bot’s name on a task before you start it.
  - Update records as their status changes, so the other bots and I see the latest version.
  - Use a unique key like a URL or email so repeat runs update records instead of duplicating them.
  - When you save something, tell me which collection it’s in.
  ```

- Your bot gives you a Hutch sign-in link. Sign in with GitHub or Google and approve access.

## Using Hutch well

- Save structured work to a Hutch collection, not a file or a chat message: tasks, leads, research, drafts, lists.
- Reuse existing collections and field names. Only create a new collection for a new kind of work.
- Before starting a task, check Hutch for records that already exist.
- Give records a status (open, in progress, done, blocked), and put your name on a task before you start it.
- Update records as their status changes, so other agents and the user see the latest version.
- Use a unique key like a URL or email so repeat runs update records instead of duplicating them.
- When you save something, tell the user which collection it’s in.

The tools behind those rules:

- hutch_list_collections and hutch_describe_collection show what exists and which fields it uses.
- hutch_query_records checks for existing records: filter for exact or numeric matches, search for free text.
- hutch_store_records saves records and creates the collection on first use.
- hutch_update_collection sets the unique key.
- The user sees every collection at https://app.hutchdb.com.

## Links

- [Home](https://hutchdb.com/index.md): what Hutch is
- [Docs](https://hutchdb.com/docs.md): connecting, every tool, filters, limits
- [Docs index](https://hutchdb.com/docs/llms.txt): the docs and every per-client guide
- [Pricing](https://hutchdb.com/pricing.md): tiers and what each includes
- [About](https://hutchdb.com/about): who runs Hutch
- [Contact](https://hutchdb.com/contact)
- [MCP server card](https://hutchdb.com/.well-known/mcp/server-card.json)
- [AI catalog](https://hutchdb.com/.well-known/ai-catalog.json)
- [Grok Bot](https://hutchdb.com/grokbot): one message connects a Grok Bot
- [Source](https://github.com/ExpeditedProjects/hutchdb): the open-source core