MCP connection guide

MCP is how an AI agent connects to Case Harvester. The server is a Streamable HTTP interface to the same data, redaction rules, and row allowance as the REST API.

Authentication and entitlement

Paste your token, which starts with chv_, into your AI agent's bearer-token setting. MCP uses the same static bearer token as the REST API, and there is no OAuth flow to configure. The token carries the same license terms and must not be shared.

Your license must include MCP access. A valid token without it receives HTTP 403 with MCP access is not included in this license.

Connect Claude Code

Put the token in an environment variable first, so the literal never lands in your shell history, then register the server:

export CASEHARVESTER_TOKEN=chv_your_token
claude mcp add --transport http caseharvester https://mcp.caseharvester.org/mcp \
  --header "Authorization: Bearer $CASEHARVESTER_TOKEN"

Add --scope user before the server name to make the connection available in every project rather than only the current directory. Verify it by running /mcp inside a session, or by asking the agent to call the usage tool.

Connect Codex

Codex reads the token from an environment variable at every launch rather than storing it, so set the variable somewhere persistent, such as your shell profile:

export CASEHARVESTER_TOKEN=chv_your_token
codex mcp add caseharvester --url https://mcp.caseharvester.org/mcp \
  --bearer-token-env-var CASEHARVESTER_TOKEN

Verify with codex mcp list, or /mcp inside a session.

Other MCP clients

Any client that speaks streamable HTTP and can send a static Authorization header connects the same way. Custom connectors on claude.ai and Claude Desktop do not qualify today: they authenticate with OAuth or not at all, and offer no field for a static bearer token.

Install the agent skill

A ready-made skill teaches an agent when to reach for Case Harvester and how to use the row allowance carefully. The server itself can only offer that guidance after a session connects. Save https://caseharvester.org/docs/mcp/skill.md as SKILL.md in a caseharvester directory under your harness's skills path: ~/.claude/skills/ for Claude Code, ~/.codex/skills/ for Codex.

Or let the agent set itself up

With your token already in the CASEHARVESTER_TOKEN environment variable, paste this into a session:

Read https://caseharvester.org/docs/mcp and connect this harness to the
Case Harvester MCP server. My token is in the CASEHARVESTER_TOKEN
environment variable; never print it. Then install the agent skill from
https://caseharvester.org/docs/mcp/skill.md. Verify the connection by calling the
usage tool and reporting my remaining row allowance.

Available tools

• describe_schema lists the queryable tables, describes one table's fields, filters, sorts and aggregations when you name it, and returns a column's allowed values when you name the column too. A long answer arrives in parts.
• query_cases retrieves one filtered and paged table. A page is 25 rows by default and at most 1,000, and offset moves to the next page. Pass columns to name the fields a question needs. The table's key columns still arrive on every row, and a reply holds many more rows. A reply also stops early when one more row would make it too large to arrive intact.
• count_cases sizes a filtered result before you retrieve it.
• aggregate_cases groups a filtered slice and counts rows or sums a published measure. A long grouping arrives in parts, and each part groups the slice again.
• get_case retrieves one case and its related records, section by section when the case is large.
• usage reports the account and your remaining row allowance.

Results include cases and charges that Case Harvester collected before they disappeared from Case Search. Each one is marked, and the methodology page explains what the marks mean.

Start with the schema

Call describe_schema before constructing filters. With no argument it lists the tables and the filter syntax, naming one returns that table's columns and operations, and naming a column as well returns its allowed values. Those are what the server supports. Use count_cases before paging through a large result, or aggregate_cases when a grouped count or sum answers the question without retrieving the underlying rows. REST, exports, and MCP all count against one rolling 30-day row allowance. Each person on an account has their own. Changing interfaces does not create a second allowance.

Large results

A reply from query_cases holds whole rows and stops before one more row would make it too large to arrive intact. It names the offset to continue from, so an AI agent can read a long result in order. On a wide table such as Charges a reply holds far fewer than 25 rows. Your AI agent can pass columns to name the fields a question needs. Each row then carries just those and the table's key columns, so a reply holds many more rows. If your AI agent stops partway through a page, Case Harvester asks it to tell you how many rows it read, that more of the page remains, and that it can read the rest. Ask it to continue when you need every row. Long answers from describe_schema, such as the table list, a wide table's columns or a long list of allowed values, a large case from get_case, one section at a time, and a long grouping from aggregate_cases arrive in parts the same way. Records that change between calls can shift the parts after them. In a describe_schema answer, nextOffset is the number of entries already sent. For allowed values it counts value groups, then parent choices, rather than values. Only the rows a reply holds count against the allowance. Each part of a grouping groups the slice again and uses another unit, as every aggregate call does.

Last updated: October 8, 2026