Server history API

Contract forge.server-history/v1 · version 1.0.0

One npm or PyPI MCP server's dated record across its versions: what happened when the House tester installed each version, a hash of the tool definitions each version listed, and what changed between consecutive versions. No account or key.

Request

GET /api/v1/history/{server}?section=all&limit=100

server is npm:name, npm:@scope/name or pypi:name, without a version, URL-encoded. Example: https://theagentforge.io/api/v1/history/npm%3A%40modelcontextprotocol%2Fserver-filesystem. Optional: section (all, install_outcomes, definitions, changes), limit (1 to 200) and offset (with one section). Each section has a next URL for its next page.

The same record is the forge_server_history tool on the /mcp/requests MCP endpoint. Machine-readable description: /openapi.json.

Response

• install_outcomes: one row per test, with its date, version, outcome and failure class (failure-classes/v1). Every row names its family: the nightly top-500 run, the weekly sweep or the backfill of older versions. Counts are per family and never added together.
• definitions: per version, the sha256 of the tool definitions and how many tools it listed. published_at (the registry's publish date) is kept apart from observed_at (when we read it): a backfilled version is what it lists when installed today.
• changes: consecutive definition sets compared: tools added or removed, descriptions or input schemas changed, whether the major version moved, and the ids of scanner rules the new text matched that the old text did not. A rule match is a pattern for a person to read, not a finding about the server.
• data_as_of: the newest timestamp among the rows read. A server with no rows answers status: "not_yet_measured".

The public tier has hashes, counts, dates and rule ids only; the tool text itself is not in it.

Caching and limits

Answers are cached for 15 minutes and carry a strong ETag; send it back in If-None-Match for a 304. 60 calls a minute per address; over that, 429 with Retry-After. The headers X-Forge-Contract and X-Forge-Contract-Version name the contract.

Versioning

Minor versions only add fields. Removing or renaming a field is a new contract (v2) at a new path; v1 keeps answering.

Sample consumer

node scripts/examples/history-consumer.mjs npm:@modelcontextprotocol/server-filesystem fetches one server's record, checks the contract version and prints its change events. It is in the public code repository.