Comparison
Static vs Dynamic agent-card: static file or SSR
A static agent-card.json is simpler, more cacheable, and more robust; SSR is only needed if data truly varies per request. Static for most.
In short
Both are valid, but for most sites a static file is better: simpler, cacheable, robust. A dynamic (SSR) card is only justified when its contents truly vary from request to request.
What each is
- Static — a JSON file at a path (
/.well-known/ai-agent.json, agent.json, MCP card), served as-is, cached by a CDN. - Dynamic (SSR) — an endpoint that generates the JSON per request: you can fill in a live rate limit, different capabilities by context, and so on.
Side by side
| Static | Dynamic (SSR) | |
|---|---|---|
| Update | Rebuild/deploy | Per request |
| Performance | CDN, very fast | Server load |
| Robustness | A file can’t “fall over” | Depends on the runtime |
| When | Stable data | Data varies per request |
Key difference
Static is a snapshot refreshed at deploy. Dynamic is a live response assembled by the runtime. SSR adds flexibility at the cost of load and a failure point.
What to choose
For most cards the data is stable (name, capabilities, endpoints) — go static: faster, cacheable, more robust. Use SSR only if a field genuinely must change dynamically (a live quota, A/B capabilities). Don’t add complexity you don’t need.
How to verify
The scanner doesn’t care how the file is generated — it checks that the right path serves valid JSON with the required fields. Static you get fast and “for free.”