Aggre

Query Aggre from an MCP client, or plain REST

Aggre serves every dataset it aggregates (Taiwan and PRC law and judgments, US medical regulation and openFDA data, SEC filings, market signals) over the Model Context Protocol, so an MCP-aware agent can browse, search and export it directly. Everything below also works as plain REST if you'd rather not run an MCP client.

Get an API key

Every MCP tool call and every REST call authenticates with an Aggre API key, and a key reads only the databases you pick for it. When you create one you also choose what it is for: Read & search covers every tool except export; pick Read, search & export if you need export_sample, export_dataset or /v1/export.

  1. Sign in with your Orbbit account. A new account starts on the Free plan with one database.
  2. On the Databases page, add the databases your plan includes.
  3. Under Access, choose "Create key", pick its databases and what it is for.
  4. Copy the secret the moment it's shown. It looks like aggre_sk_… and is only ever displayed once.

Connect

Two ways to reach the same 15 tools. Pick whichever fits your client.

Native MCP (Claude Desktop, Claude Code, any MCP client)

Build the stdio server from the Aggre-Infra repo, then point your client's MCP config at the binary:

cargo build --release -p aggre-mcp
{
  "mcpServers": {
    "aggre": {
      "command": "/absolute/path/to/Aggre-Infra/target/release/aggre-mcp",
      "env": {
        "AGGRE_API_BASE": "https://aggre.orbbit.ai",
        "AGGRE_API_KEY": "aggre_sk_..."
      }
    }
  }
}

Set AGGRE_API_BASE explicitly. It defaults to http://127.0.0.1:8080 when unset, so leaving it out silently points the server at your own machine instead of https://aggre.orbbit.ai.

Claude Code users can install the packaged skill instead of hand-writing the config:

git clone https://github.com/OrbbitAI/Aggre-MCP-Skill.git .claude/skills/aggre-mcp

Direct REST

No build step, no MCP client: two endpoints. Either x-aggre-api-key or Authorization: Bearer works as the auth header.

curl -H "Authorization: Bearer aggre_sk_..." \
  https://aggre.orbbit.ai/v1/mcp/tools
curl -X POST https://aggre.orbbit.ai/v1/mcp/call \
  -H "Authorization: Bearer aggre_sk_..." \
  -H "content-type: application/json" \
  -d '{
    "name": "retrieve",
    "arguments": { "query": "動產擔保交易", "corpus": "laws", "top_k": 5 }
  }'

Tools

15 tools. A read key reaches all of them except the two export tools. Arguments are strict: an unknown argument name is an error, not silently ignored. ! marks a required argument.

list_datasetsread
Browse the catalog — every dataset your key can read, optionally filtered.category?, tags?, query?
get_dataset_schemaread
Inferred field schema for a dataset, with sensitive fields flagged.dataset_id!, limit? (1–100)
get_recordread
Fetch one record by id.id? | record_id?
search_datasetread
Keyword search scoped to a single dataset.dataset_id!, query!, limit? (1–50)
retrieveread
Two-stage semantic (RAG) search across a corpus — see below for detail.query!, corpus?, jurisdiction?, dataset?, top_k?, depth?, candidates?, threshold?, rerank_chars?, stage1_timeout_secs?
retrieve_batchread
Several retrieve queries in one call, sharing retrieve's options.queries!, plus retrieve's shared arguments
search_judgmentsread
Taiwan case law searched by the court's reasoning (理由 and 主文 passages), not just the caption.query!, court_level?, case_type?, date_from?, date_to?, max_results?
get_judgmentread
Read a judgment found by search_judgments or lookup_judgment, a page at a time.doc_id!, offset? | around?, max_chars?
lookup_judgmentread
Resolve a citation such as 最高法院49年台上字第1730號 to the judgment.citation!, court?
get_politician_tradesread
US Senate STOCK Act disclosures.(no required arguments)
get_investor_holdingsread
13F holdings for a tracked fund/investor.investor!
get_insider_tradesread
SEC insider transaction filings.(no required arguments)
who_tradedread
Every tracked trade (politician + insider) touching one ticker.ticker!
export_sampleexport
Small sample export for eyeballing shape/quality before a real pull.dataset_id!, limit? (1–100)
export_datasetexport
Bulk, paginated export.dataset_id!, limit? (1–2000, default 500), offset?

retrieve, in depth

retrieve is the semantic search tool: a two-stage pipeline (trigram recall, then a reranker) over whichever corpus you pick, rather than an exact-keyword match.

corpus

  • laws
  • judgments
  • both
  • medical
  • medical-laws
  • medical-judgments
  • drug-labels
  • fda-safety
  • sec-filings
  • 510k
  • device-summaries
  • device-classification

jurisdiction

TW (default), CN, or US. Narrows a corpus that spans more than one jurisdiction; US-only corpora ignore it.

Reading the response honestly

Every response carries complete, timed_out, and recall_only. A large or common-term query can fall back to an unordered recall sample rather than a fully ranked one, so check these three fields before treating results as exhaustive or perfectly ordered. Each hit carries rerank_score, lexical_score, a snippet, and full source citation fields (court, case_number, law_name, article_no, source_url, and more, depending on corpus).

Current datasets

Live record counts and search capability for every dataset your key can read, refreshed hourly from the same census the console uses.