Changelog

• Signing in no longer costs you the free trial. A signed-in account that is not on Pro used to be refused on every MCP tool, including the five an anonymous connection could use. It now keeps the free trial: the five trial tools answer with the trial caps, counted as 10 calls a day for the account, and the other tools answer that they need the Pro plan. Upgrading reaches an open connection within a minute, with nothing to reconnect.
• Without signing in, the 10 trial calls a day are shared by everyone on the same network address. When they run out, the next trial call on https://mcp.ensemblai.com/mcp returns the OAuth sign-in challenge (HTTP 401), so Claude asks you to sign in, and a free account then has its own 10 a day. The /try address, and clients that send an empty or placeholder key, still get a message instead.
• Every trial response now states the caps it applied in _trial.caps (10 rows, 6 months, monthly data). A trial call from a signed-in account that passes an argument the trial cannot apply (domain, category, offset) is refused without using a call, instead of answering without it.
• API keys work as before. They are the way in for scripts, CI and clients that cannot open a browser; in Claude, sign in.

• Sign in when a tool needs it. Connecting to https://mcp.ensemblai.com/mcp without signing in now lists all 32 tools. The five trial tools work as before; calling any other tool returns an OAuth sign-in challenge (HTTP 401), so Claude asks you to sign in and runs the call once you are signed in with a Pro account. Signing in and API keys work as before. The /try address, and clients that send an empty or placeholder key (the Claude Code plugin before a key is set), still list only the five trial tools.
• Every tool now has a title and hints that say whether it only reads or changes your saved items. The seven tools that add, change or delete watchlist entries, alerts and ensembles are marked destructive, so clients ask before running them.
• The OAuth protected-resource metadata names the authorization server exactly as its issuer (https://clerk.ensemblai.com, without a trailing slash) and is also served at /.well-known/oauth-protected-resource.

• breakdown=arch adds other_arch_downloads: the downloads in neither x86_64_downloads nor arm_downloads (Windows, which reports AMD64 / ARM64; clients that report no CPU; rarer chips). The three now add up to total_downloads. It is derived from the stored counts, so it covers all history, and it is null for npm, which has no architecture split. It is also returned wherever both architecture fields are: with breakdown=full, on ensemble analytics, and on /v1/packages/{name}/metrics.
• Faster first requests for listings filtered by a domain and/or a category on /v1/packages, and for the domain and category lookups behind leaderboards, time series and aggregates. Results are unchanged.
• MCP server 3.0.1 and documentation: the MCP and agent instructions, llms.txt and these docs state the current classification (20 domains and 80 categories) and 2.5M pre-computed rollup rows, and the trial instructions say that a key or sign-in upgrades the same connection. The tools are unchanged.

• Versioning. The REST schema version is now the release number; it read 1.0 through every earlier change. The MCP server now reports its own version, 3.0.0; before this it reported 2.13.1, which was the version of the framework it is built on. Both move with every release, and this page records what changed.
• Breaking: more than 25 packages on /v1/analytics/time-series returns 422 instead of 400, like every other validation error. The error code and message are unchanged.
• /v1/leaderboards/downloads, and the MCP top_downloads tool, answer a filter value that matches no packages with a NO_MATCHING_PACKAGES warning next to the empty list. Before, the list was empty with no explanation, which reads as “nothing in this domain” when the value is usually misspelled.
• Optional size controls, matching the MCP tools: /v1/ecosystem takes top_domains and categories_per_domain, and the /v1/reference/* lists take contains and limit. Without them the responses are exactly as before.
• Documentation: the period parameters of /v1/companies, /v1/organizations, /v1/organizations/{github_org}/packages and /v1/analytics/version-adoption list their accepted values (the schema already enumerated them); breakdown=arch says which downloads fall in neither column; compare_packages is documented as taking up to 10 names, one included.

• Weekly and monthly series, aggregates and month anchors now end at the newest period whose last day is fully counted. PyPI data is ingested on Sundays, so the week ending on that Sunday, and a month whose last days come after the run, are withheld until the next run fills them. Before, they were served as complete from the Monday or the 1st while about 8% (a week) or up to 13% (a month) short.
• npm weeks and months are served only once they match npm’s own numbers, and are re-checked every week, because npm fills in its download counts days or weeks after the fact.

• Breaking: every error, validation errors included, uses one envelope: error.code, error.message and, where there is more to say, error.details. The legacy top-level detail field was removed.
• The /v1/reference/* lists take an optional ecosystem; without it they cover both ecosystems, as before.

Several parameters were accepted and silently ignored or truncated. They now either work as documented or return a 422 that says why. Where the dashboard or a saved agent artifact can send a value, it is served and explained in warnings instead.

• Breaking: /v1/ecosystem accepts only period=30d. The map has always covered the latest complete month; 90d and 365d were accepted and ignored. For longer windows use /v1/analytics/time-series with domain aggregates.
• Breaking: the MCP ecosystem_map tool no longer takes period; top_domains, categories_per_domain and top_packages size the answer.
• Breaking: period on companies, organizations and version adoption is limited to its listed values; anything else returns 422 instead of being served as 30 days.
• Breaking: /v1/analytics/growth takes mom, qoq or yoy (30d, 90d and 365d are accepted as aliases), and returns 422 for anything else or for more than 25 packages, instead of cutting the list. Geography over 10 packages and version adoption over 10 versions return 422 instead of being cut.
• Breaking: an unknown country_grouping or metric on the time series returns 422. Aggregates past the limit, or that match nothing, are named in warnings.
• Breaking: dates must be YYYY-MM-DD on every dated endpoint; a malformed date used to fail with a 500.
• Breaking: MCP compare_packages refuses more than 10 names instead of dropping the rest, and tool failures are reported as errors rather than as successful results.
• /v1/status is public and returns status, version, a timestamp and data freshness only. On API-key requests the x-ratelimit-* headers carry your real limit. Adding a package already on your watchlist returns 409.