How to use cohort intelligence in a Claude agent
— full tutorial.

The Chart Library MCP server is a Python package on PyPI. From any terminal:

pip install chartlibrary-mcp

That installs the chartlibrary-mcp command and the underlying SDK. It speaks the standard Model Context Protocol, so any MCP-aware client (Claude Desktop, Cursor, Cline, custom Python harnesses) can consume it.

Sign up at chartlibrary.io/developers. The Sandbox tier is free and gives you 200 calls/day on the search, follow-through, and context endpoints. Full cohort intelligence (cohort_analyze, narrative_pulse, cohort_compare) is part of Builder tier at $29/mo.

If you’re an active integrator and the 200/day Sandbox cap is in your way for evaluating the cohort endpoints, email graham@chartlibrary.io with a sentence on what you’re building and we’ll comp you Builder for 90 days.

Copy the API key (starts with `cl_`).

Claude Desktop

Open the Claude Desktop MCP config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the chartlibrary-mcp server entry:

{
  "mcpServers": {
    "chartlibrary": {
      "command": "chartlibrary-mcp",
      "env": {
        "CHARTLIBRARY_API_KEY": "cl_your_key_here"
      }
    }
  }
}

Restart Claude Desktop. The Chart Library tools appear in the tool picker.

Cursor

Cursor uses the same MCP config format. Open Cursor’s settings → MCP and add:

{
  "chartlibrary": {
    "command": "chartlibrary-mcp",
    "env": {
      "CHARTLIBRARY_API_KEY": "cl_your_key_here"
    }
  }
}

Cursor will reload and the tools become available to Composer.

Custom Python client

If you’re writing your own Anthropic SDK harness, you can invoke chartlibrary-mcp as a subprocess and pipe MCP messages, OR call the underlying REST API directly. The REST path is often simpler for embedded use cases:

import os
import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-haiku-4-5-20251001",
    max_tokens=2048,
    tools=[{
        "name": "cohort_analyze",
        "description": "Get Layer 3 cohort intelligence for a (symbol, date) anchor",
        "input_schema": {
            "type": "object",
            "properties": {
                "symbol": {"type": "string"},
                "date": {"type": "string"},
                "timeframe": {"type": "string", "default": "1d"},
            },
            "required": ["symbol", "date"],
        },
    }],
    messages=[{"role": "user", "content": "Analyze NVDA on 2024-08-05"}],
)

In Claude Desktop or Cursor, ask:

What's the historical cohort for NVDA on 2024-08-05 at the 1-hour timeframe?

Claude will invoke cohort_analyze with that anchor. You’ll see a tool-call card showing the request, then Claude’s structured response describing:

• The 300 historical analogs that look most like NVDA at that moment
• The full forward-return distribution at 1, 5, and 10 days (median, p10/p90, win rate, std)
• Which features separated winning analogs from losing ones
• How the cohort splits by current market regime

The raw response is JSON and runs ~2-5 KB. Claude summarizes it inline. If you want the raw structure, ask “show me the raw cohort_analyze response” — the agent will print it.

A single cohort call is fine. A few chained calls is where the agent really shines. The MCP server exposes composite tools: cohort_analyze, get_market_context, narrative_pulse, discover_picks, plus search and explain helpers. The agent decides which to chain.

Pattern that works well:

> What does NVDA look like right now?

# The agent:
# 1. get_market_context()  - VIX, yield curve, sector rotation, breadth
# 2. cohort_analyze(NVDA, today, 1d)  - 300 analogs, full distribution
# 3. narrative_pulse(NVDA)  - news sentiment + divergence score
# 4. Synthesizes all three into a multi-factor view

That’s the chain we evaluated in the ADQE paired-agent eval — and it’s the reason cohort-equipped agents beat baseline-equipped agents 50-0 across 50 out-of-sample scenarios. The chain gives Claude enough structured facts that it can produce a defensible analysis instead of pattern matching from training data.

Out of the box Claude will use the tools when the user asks for analysis. But three system-prompt patterns make the agent meaningfully more reliable:

Pattern 1: Anchor discipline

When the user asks about a stock, ALWAYS resolve the question to
a (symbol, date, timeframe) anchor before any analysis. If the
date is unspecified, default to today's date. If the timeframe is
unspecified, default to "1d" for multi-day questions and "1h" for
intraday questions.

Without this, Claude will sometimes ask vague follow-up questions instead of making a tool call. With it, the agent acts.

Pattern 2: Always cite the cohort

Every assertion about future behavior must be backed by a specific
field from a cohort_analyze response. Never write "the stock will
probably rise" without referencing the cohort median, win rate, or
regime stratification. If the cohort data doesn't support a claim,
say so plainly.

This is what kept the with-layer agent grounded in the ADQE eval. The judge specifically called out citation density as a major separator between the two agents.

Pattern 3: Stratify before concluding

Always check the regime_stratification block before forming a
conclusion. If the cohort splits sharply by regime (e.g. high-vol
analogs perform very differently from low-vol analogs), prefer
the regime-conditioned view to the headline statistic.

The base-rate vs regime-conditional distinction is the single most important judgment call an analyst makes. The system prompt encodes it.

Patterns that work

• Cohort first, then narrative. Get the historical base rate before introducing news context. News without a base rate over-weights the most recent story.
• Regime context once per session. get_market_context is cheap and the result applies across all subsequent analyses in the conversation. Call it once at the start.
• Use feature_importance to look ahead. When the cohort response surfaces a feature like credit_spread_state=tight (positive), the agent should check whether that feature is currently present.

Anti-patterns to avoid

• Over-filtering. Adding too many filters shrinks the cohort below the n=30 floor. The API warns when this happens — listen to the warning.
• Treating the median as a forecast. The median is the center of a distribution that runs from p10 (often -10%+) to p90 (often +10%+). The distribution is the answer; the median is just one summary.
• Calling cohort_analyze in a loop without rate- limiting context. Builder tier is 60 RPM. Agent loops that call cohort_analyze 20 times to “explore options” will burn through quota fast. Use discover_picks or get_daily_setups for screen-style queries.
• Asking Claude to predict. Cohort intelligence is empirical, not predictive. Frame agent queries as “what did analogs do” not “what will this do.” The agent answers better.

Here’s a transcript shape that consistently produces high-quality output:

USER: NVDA looks shaky after this morning's drop. Should I be
worried about a 5-day hold from here?

CLAUDE [tool: get_market_context]: VIX 17.4, yield curve flat,
  SPY ret_20d +2.1%, breadth weakening. Macro state: neutral-bullish.

CLAUDE [tool: cohort_analyze]: NVDA · today · 1d. Cohort n=300.
  5d median return: -0.6%, win rate 49%, p10/p90 -8.4%/+7.1%.
  Feature importance: realized_vol_20d=high (negative, top factor),
  macro_state=neutral (positive), days_since_earnings<10 (negative).
  Regime stratification: high-vol analogs win 42%, low-vol 55%.

CLAUDE [response]: The 300-analog cohort suggests a slightly bearish
  to neutral 5-day outlook (median -0.6%, win rate 49%). The signal
  splits sharply on vol regime — high-vol analogs win 42% of the
  time vs 55% for low-vol. NVDA is currently in a high-vol regime
  (realized_vol_20d at the top quartile), and that's the dominant
  separator in the cohort. Earnings is 8 days out, which is also a
  negative factor.

  Net: yes, caution is warranted on a 5-day hold from here. If you
  do hold, your downside is structurally wider than a typical NVDA
  setup — the p10 is -8.4% vs a more usual -5%.

That’s an analysis paragraph any portfolio manager would recognize. The agent didn’t predict — it grounded every claim in a retrievable historical fact.

Do I need a paid tier to use cohort intelligence in a Claude agent?

Yes — the cohort_analyze endpoint (and Layer 3 endpoints like narrative_pulse, cohort_compare) are part of the Builder tier from $29/mo. Search, follow-through, and context endpoints work on the free Sandbox tier so you can wire the agent and test it before subscribing. Active integrators can email graham@chartlibrary.io for a 90-day Builder comp.

How long does a cohort_analyze call take?

Median ~280 ms. The full response (300-analog cohort + outcome distribution at 3 horizons + feature importance + regime stratification + risk profile) is computed and returned in a single round trip. For Claude Desktop or Cursor that's effectively instant.

Does the MCP server work with Cline and other MCP clients?

Yes. chartlibrary-mcp speaks standard Model Context Protocol — any MCP-compatible client (Cline, Continue, custom Python harnesses) can consume it. Configuration follows the client's MCP config format.

How do I avoid burning through my call quota in an agent loop?

Three patterns: (1) Call get_market_context once per conversation, not per anchor; (2) Use discover_picks or get_daily_setups for screen-style queries instead of looping cohort_analyze; (3) Cache the cohort response in the conversation context so the agent can revisit it without re-querying.

Can I see what tools Claude is calling in real time?

Yes. Claude Desktop shows tool-call cards inline as the agent invokes them. Cursor's Composer shows the same. For programmatic use, the Anthropic SDK returns stop_reason='tool_use' with the tool name and input — your harness can log them.

What's the best Claude model for this?

We use Claude Haiku 4.5 as the agent model in production and in the ADQE eval. Sonnet works too but is overkill for the typical cohort-call-and-reason loop — Haiku is faster, cheaper, and produced 50-0 wins in the paired evaluation. Use Sonnet when you need very long-form synthesis on top of the cohort data.