API and MCP
Everything on usecase.to can be read from code. The JSON API is for apps and scripts. The MCP server is for AI agents. Both are free, need no key, and return the same stories the site shows.
- Base URL
https://usecase.to- MCP endpoint
https://usecase.to/mcp- Authentication
- None
- Format
- JSON
- Rate limit
- 240 requests a minute per IP address
Quickstart
List the products, then ask for stories about one of them by its slug.
curl https://usecase.to/api/products
curl "https://usecase.to/api/stories?product=instinct&limit=5"
To let an agent read them, add the MCP server to your client. In Cursor:
{
"mcpServers": {
"use-case": { "url": "https://usecase.to/mcp" }
}
}
API basics
The API has three read-only endpoints: products, stories, and one story by id. The site's feed uses these same endpoints, so a request returns the stories the site shows, in the same order.
Authentication
There is none. Every endpoint is public. Responses carry Access-Control-Allow-Origin: *, so a browser can call the API from any site.
Responses
Every response is JSON. A successful response may be cached for 30 seconds (Cache-Control: public, max-age=30). Errors are never cached, so a retry reaches the server. Larger responses are compressed with Brotli or gzip when the client accepts it.
Pagination
The list endpoints take limit and offset and return a pagination object next to data:
{
"data": [ ... ],
"pagination": { "limit": 36, "offset": 0, "hasMore": true }
}
hasMore tells you whether another page exists. There is no total count. To read everything, add limit to offset until hasMore is false:
const stories = [];
let offset = 0;
while (true) {
const url = `https://usecase.to/api/stories?product=instinct&limit=100&offset=${offset}`;
const { data, pagination } = await (await fetch(url)).json();
stories.push(...data);
if (!pagination.hasMore) break;
offset += pagination.limit;
}
limit runs from 1 to 100, and offset from 0 to 10,000. A value outside those ranges is clamped, not rejected.
Errors
An error returns a status code and a JSON body with a message:
{ "error": "No product named \"nope\"." }
| Status | Meaning | Example message |
|---|---|---|
400 | The request is malformed. | order must be "ranked" or "newest". |
404 | The product, story, or route does not exist. | No story with id 999999. |
429 | Too many requests. Wait Retry-After seconds. | Too many requests. Try again in 12s. |
500 | Something failed on our side. | Something went wrong |
An unknown product is a 404 rather than an empty list, so a typo in a slug fails loudly.
Rate limits
Each IP address can make 240 requests a minute, shared between the API and the MCP server. Past that, requests get a 429 with a Retry-After header until the minute is up.
Endpoints
List products
GET/api/products
Returns every product, in the order the site lists them. Each has the slug the story endpoints take.
Query parameters
-
featuredbooleanoptionaltruereturns only the products featured on the site.falsereturns the rest. Omit it for all products. -
limitintegeroptionalProducts to return, 1 to 100. Defaults to 100.
-
offsetintegeroptionalProducts to skip. Defaults to 0.
Returns a list of product objects.
curl "https://usecase.to/api/products?limit=2"
{
"data": [
{
"id": 1,
"slug": "instinct",
"name": "Instinct",
"position": 1,
"featured": true,
"pictureUrl": "https://instinct.com/favicon.svg",
"color": "#060A09",
"storyCount": 145
},
{
"id": 2,
"slug": "muse",
"name": "Muse",
"position": 2,
"featured": true,
"pictureUrl": "https://example.com/muse.jpg",
"color": "#0064E0",
"storyCount": 156
}
],
"pagination": { "limit": 2, "offset": 0, "hasMore": true }
}
List stories
GET/api/stories
Returns stories for one product, or for every product when product is omitted.
Query parameters
-
productstringoptionalA product slug such as
claude-code. A numeric product id also works. An unknown product returns a404. -
orderstringoptionalranked(default) is the order the site uses.newestis strictly newest first. Anything else returns a400. -
limitintegeroptionalStories to return, 1 to 100. Defaults to 36.
-
offsetintegeroptionalStories to skip. Defaults to 0.
Returns a list of story objects.
How ranking works. A story's score halves every 36 hours, and engagement on the original post can at most double it. So a popular story only outranks stories of roughly its own age, and the top of the feed stays fresh.
curl "https://usecase.to/api/stories?product=instinct&limit=1"
{
"data": [
{
"id": 1401,
"productId": 1,
"productSlug": "instinct",
"title": "Planned a surprise",
"content": "Told my Instinct to plan a surprise with my partner's.",
"url": "https://x.com/someone/status/123",
"source": "x",
"username": "someone",
"profilePictureUrl": "https://example.com/avatar.jpg",
"media": [
{ "url": "https://example.com/photo.jpg", "type": "photo", "width": 1768, "height": 2336 }
],
"createdAt": "2026-09-22T03:34:54.194448+00:00"
}
],
"pagination": { "limit": 1, "offset": 0, "hasMore": true }
}
Retrieve a story
GET/api/stories/:id
Returns one story object, without the data wrapper. An id that is not a positive whole number returns a 400. An id with no story returns a 404.
curl https://usecase.to/api/stories/1401
Health check
GET/health
Returns {"ok":true} while the server is up.
Objects
The product object
-
idintegerUnique identifier.
-
slugstringURL-safe name to pass to the story endpoints.
Claude Codeisclaude-code. -
namestringDisplay name.
-
positionintegerOrder in the site's product list.
-
featuredbooleanWhether the site features this product at the top of its list.
-
pictureUrlstring or nullThe product's logo.
-
colorstring or nullThe product's brand color, as any CSS color.
-
storyCountintegerHow many stories the product has.
The story object
-
idintegerUnique identifier. Pass it to Retrieve a story.
-
productIdintegerThe
idof the product the story is about. -
productSlugstringThe
slugof the product the story is about. -
titlestring or nullA short title, when the post has one.
-
contentstring or nullThe story, in the words of the person who posted it.
-
urlstringThe original post. Keep this link with the text if you quote a story.
-
sourcestringWhere it was posted:
x,reddit,hacker_news, orlinkedin. -
usernamestring or nullThe author's name on that site.
-
profilePictureUrlstring or nullThe author's picture, loaded from the site the story came from. It can stop working at any time, so show a fallback.
-
mediaarray or nullOne to four images or videos from the post. Each has a
url, awidth, and aheightin pixels, and usually atypesuch asphoto. -
createdAtstringWhen the story was added, as an ISO 8601 timestamp.
MCP server
The MCP server gives agents three tools that call the same code as the API. It speaks Model Context Protocol over streamable HTTP at https://usecase.to/mcp.
The server is stateless: there are no sessions, so every request stands alone and a dropped connection has nothing to resume. It replies with plain JSON, not an event stream. There is no authentication.
Connect a client
Cursor. Add this to .cursor/mcp.json in a project, or to ~/.cursor/mcp.json for every project.
{
"mcpServers": {
"use-case": { "url": "https://usecase.to/mcp" }
}
}
Claude Code. Run this in your project. Add --scope user to make it available in every project.
claude mcp add --transport http use-case https://usecase.to/mcp
Other clients. Use the URL https://usecase.to/mcp with the streamable HTTP transport. Clients that ask for a transport type in their config, such as a Claude Code .mcp.json, want "type": "http" next to the url.
When a client connects, the server tells the agent to start with list_products and to keep a story's source link with anything it quotes.
Tools
Each tool returns the same JSON as the matching API endpoint, as a single text block.
list_products
Every product, with its slug and story count. Call this first: the story tools take a slug, not a name.
-
featuredbooleanoptionaltruefor only the featured products,falsefor the rest. -
limitintegeroptional1 to 100.
-
offsetintegeroptionalRows to skip.
pagination.hasMorein the reply says whether more remain.
list_stories
Stories for one product, or for every product when product is omitted.
-
productstringoptionalA slug from
list_products, such as"claude-code". -
order"ranked" | "newest"optionalDefaults to
"ranked", the order the site uses. -
limitintegeroptional1 to 100. Defaults to 36.
-
offsetintegeroptionalRows to skip.
get_story
One story by the id list_stories returned.
-
idintegerrequiredThe story id.
Try it with curl
Because the server is stateless, you can call a tool directly with one JSON-RPC request:
curl https://usecase.to/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": { "name": "list_stories", "arguments": { "product": "instinct", "limit": 1 } }
}'
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{ "type": "text", "text": "{\n \"data\": [ ... ],\n \"pagination\": { ... }\n}" }
]
}
}
Send "method":"tools/list" instead to see every tool with its input schema.
Tool errors
An unknown product or a missing story comes back as a normal result with isError set, not a protocol error, so the model gets a message it can act on:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [{ "type": "text", "text": "No product named \"nope\"." }],
"isError": true
}
}
Where the stories come from
Stories are public posts from Reddit, X, and Hacker News. We didn't write them and we don't own them. Every story includes its url. Keep that link with the text wherever you show it.