AAggre
Sign in

Developer guide

Query Aggre from an MCP client, or plain REST

Aggre serves every dataset it aggregates — Taiwan/China legal research, SEC medical & biotech filings, openFDA drug data, and market/insider 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 at all.

Get an API key

Every MCP tool call and every REST call authenticates with the same Aggre API key. A key created from the console already carries every scope MCP needs — McpRead, DatasetRead, SearchRead, and ExportWrite — so there's nothing extra to request.

  1. Sign in to the console (or create an owner key straight from the sign-in page if this is a brand-new org).
  2. Open the Access panel and choose "Create API key".
  3. Copy the secret the moment it's shown — it's generated as aggre_sk_… and only ever displayed once.

Connect

Two ways to reach the same eleven 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 — 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 — just 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

Eleven tools, gated by the same scopes a default API key already has. Arguments are strict — an unknown argument name is a hard error, not a silent ignore.

list_datasetsDatasetRead

Browse the catalog — every dataset your key can read, optionally filtered.

category?, tags?, query?
get_dataset_schemaDatasetRead

Inferred field schema for a dataset, with sensitive fields flagged.

dataset_id!, limit? (1–100)
get_recordDatasetRead

Fetch one record by id.

id? | record_id?
search_datasetSearchRead

Keyword search scoped to a single dataset.

dataset_id!, query!, limit? (1–50)
retrieveSearchRead

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?
get_politician_tradesSearchRead

US Senate STOCK Act disclosures.

(no required arguments)
get_investor_holdingsSearchRead

13F holdings for a tracked fund/investor.

investor!
get_insider_tradesSearchRead

SEC insider transaction filings.

(no required arguments)
who_tradedSearchRead

Every tracked trade (politician + insider) touching one ticker.

ticker!
export_sampleExportWrite

Small sample export for eyeballing shape/quality before a real pull.

dataset_id!, limit? (1–100)
export_datasetExportWrite

Bulk, paginated export.

dataset_id!, limit? (1–2000, default 500), offset?

retrieve, in depth

retrieve is the semantic (RAG) 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 this).

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 — 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, refreshed hourly from the same census the console itself uses — not a hand-maintained list that drifts out of date.