use case Docs

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.

Terminal
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:

.cursor/mcp.json
{
  "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:

Response
{
  "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:

JavaScript
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:

Response · 404
{ "error": "No product named \"nope\"." }
StatusMeaningExample message
400The request is malformed.order must be "ranked" or "newest".
404The product, story, or route does not exist.No story with id 999999.
429Too many requests. Wait Retry-After seconds.Too many requests. Try again in 12s.
500Something 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

Returns a list of product objects.

RequestOpen
curl "https://usecase.to/api/products?limit=2"
Response
{
  "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

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.

RequestOpen
curl "https://usecase.to/api/stories?product=instinct&limit=1"
Response
{
  "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.

Request
curl https://usecase.to/api/stories/1401

Health check

GET/health

Returns {"ok":true} while the server is up.

Objects

The product object

The story object

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.

.cursor/mcp.json
{
  "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.

Terminal
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.

list_stories

Stories for one product, or for every product when product is omitted.

get_story

One story by the id list_stories returned.

Try it with curl

Because the server is stateless, you can call a tool directly with one JSON-RPC request:

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 } }
  }'
Response
{
  "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:

Response
{
  "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.