ressource.socialbetadocumentation
MCP server

MCP server

Let Claude or any other MCP client search, read, save and organize your sources.

ressource.social runs a Model Context Protocol server over your Library. Connect an assistant to it and the assistant can search your sources, read them, save new pages for you and file them into folders. It uses the same services and the same credentials as the open API, so it isn't a second API.

Server URL
https://www.ressource.social/api/v1/mcp

Use the www host

The apex domain ressource.social redirects to www.ressource.social. A client set up with the apex URL follows the redirect and then rejects the server's OAuth metadata, because the address it was given and the one that answered don't match. Always use https://www.ressource.social/api/v1/mcp.

What an assistant can do

Twelve tools in all. Every one of them works only on your own Library:

  • Find: search your sources, list them by folder or tag, and read one in full, including its comments and the communities it is shared with.
  • Save: save one page or up to ten at once. Each save can go into a folder, with tags and a description. ressource.social fetches the page's title and preview itself.
  • Organize: list your folders as a tree, create, rename or move folders, move up to 500 sources in one call, and suggest existing tags to reuse.

There is no tool that deletes a source, shares a source into a community, comments, reacts or touches your account. You do those in ressource.social. The full list is on Tools.

Transport

The server speaks stateless Streamable HTTP:

  • Every JSON-RPC message is its own POST to the server URL, and no session is kept between requests.
  • Send one message per request. A JSON-RPC batch (an array) is refused with 400 validation_failed.
  • Send Accept: application/json, text/event-stream, as the Streamable HTTP spec requires.

A failed tool call comes back as a tool result with isError: true and a message such as not_found: Source not found, so the assistant can read it and try again. If authentication fails, or a rate limit is hit, before any tool runs, the response uses the API's usual error envelope and status code.

Authentication

The server accepts a bearer token only. A browser session cookie is refused. There are two ways to get a bearer token.

This is the path for Claude (claude.ai, Claude Desktop, mobile), Claude Code and any client that can open a browser. You have no token to copy:

  1. The client calls the server without a token and gets a 401 whose WWW-Authenticate header points to the protected-resource metadata at https://www.ressource.social/.well-known/oauth-protected-resource/api/v1/mcp.
  2. From there it finds the authorization server and registers itself. It then sends you to a ressource.social consent page in your browser.
  3. On the consent page you sign in if you need to, check which account is shown and choose allow access. The page shows the name the app gave itself and where your browser will be sent back to.
  4. The client receives an access token and a refresh token, and it renews the access token on its own. Each access token lasts one hour.

Access lasts until you disconnect the app in Settings → Integrations, under connected apps. Disconnecting takes effect on the app's next request.

What an app connected with OAuth can't do

An OAuth connection has read and write access, but never to a tool whose effect can't be undone. Today that tool is delete_folder: an OAuth client doesn't see it in tools/list, and calling it by name fails. The token is also accepted only by the MCP server. Every other /api/v1 route answers 403 to it.

Personal access token

This option is for scripts, for clients that can't open a browser, and for anyone who wants a narrower token. Create a token in Settings → Integrations and send it as a bearer header on every request:

Authorization: Bearer rsk_…

The token's scopes decide which tools it sees:

  • A read token gets only the five read tools. Write tools don't appear in its tools/list.
  • A write token gets all twelve, delete_folder included.

If you revoke a token, the client gets a 401 on its next request. See Authentication for how tokens work across the whole API.

Rate limits

Every MCP request counts as one request: initialize, tools/list and each tools/call. An over-limit request is answered with HTTP 429 rate_limited and a Retry-After header before any tool runs, so nothing is ever half done.

CredentialWindow
Personal access tokenThe token's own per-minute quota, the same one it spends on the REST API. The default is 120 a minute, and you can set 30, 60, 120 or 300 per token in Settings.
OAuth120 requests a minute per user, shared by every app you have connected.

A tool call costs one request no matter how much it does. But the work inside it still spends your account's own limits:

  • Every new page saved counts against your hourly and daily save limits. When a batch hits that limit, the remaining URLs come back as rate_limited inside a normal result.
  • Bulk moves have their own hourly and daily windows.
  • Saving a URL that is already in your Library is free.

Details are on Rate limits.

Next

Connect a client

Set up Claude, Claude Code, Cursor and other MCP clients.

Tools

Every tool, what it does, and the inputs it takes.

TypeScript client

Call the API with compile-time checked paths, parameters and bodies, using types generated from openapi.json and openapi-fetch.

Connect a client

Add the ressource.social MCP server to Claude, Claude Code, Cursor or any other remote MCP client.

On this page

What an assistant can doTransportAuthenticationOAuth (recommended)Personal access tokenRate limitsNext