Nemos for developers and AI agents

Nemos is a save-and-find app for iPhone, iPad and Apple Watch. Each person's library lives in their own iCloud account, so no API reads across everyone's data. What you can build on is a small public API on nemosapp.com and an MCP server that lets an assistant read one person's library after that person signs in and agrees.

Machine-readable files

• OpenAPI 3.1 description: Every public endpoint, typed, with operation IDs and the OAuth scope.
• API catalog (RFC 9727): Linkset pointing at each API, its description, docs and status.
• MCP server card: The hosted MCP server's name, version and address (also listed in /.well-known/ai-catalog.json).
• llms.txt: A short index of the site for language models; llms-full.txt has the detail.
• Sitemap: Every indexable page.

Markdown for agents

Every page on nemosapp.com answers in Markdown when the request asks for it, from the same URL, with Vary: Accept. HTML stays the default. A request that accepts neither HTML nor Markdown gets 406 Not Acceptable.

curl -H "Accept: text/markdown" https://nemosapp.com/

Endpoints

The public endpoints need no key and no account: call them now, for example /api/v1/health. Their exact parameters and response shapes are in openapi.json.

Versioning and deprecation

The version is in the path: /api/v1/. New fields and new endpoints are added within v1, so ignore fields you do not know. A breaking change ships as /api/v2/ alongside v1, never in place. Before a path is retired it answers with a Deprecation header (RFC 9745) and a Sunset header (RFC 8594) that names the day it stops, and the change is listed here. The unversioned /api/<name> paths are aliases of v1, kept for links already published: share images and the unsubscribe link in emails.

Rate limits

Each client may make 120 requests a minute to /api/. Every API response says where you stand, with the IETF RateLimit fields and the older trio many clients read:

RateLimit-Policy: "default";q=120;w=60
RateLimit: "default";r=119;t=60
RateLimit-Limit: 120
RateLimit-Remaining: 119
RateLimit-Reset: 60

Past the limit the answer is 429 with a Retry-After header (seconds) and a rate_limited error body. The hosted MCP server has its own per-account limits, listed on the MCP server page.

Hosted MCP server

https://mcp.nemosapp.com/mcp is a remote MCP server over Streamable HTTP. After the person who owns a Nemos library signs in, their AI assistant can use five read-only tools on that library:

• search_nemos: Search the connected user's saved notes, screenshots, links and other items by text.
• get_item: Read the full saved text of one item returned by search, by its ID.
• get_related_items: Find saved items related to one item by shared folders, tags or category.
• get_recent_items: List recently saved or updated items.
• build_context_pack: Gather relevant saved items with source excerpts for the assistant to cite.

In an assistant that supports remote MCP servers with OAuth (Claude's custom connectors, for example), add it by its URL and the assistant runs the sign-in. To run it on your own machine instead, with its full tool set, use the command-line tool below.

Command-line tool (npm)

nemos-mcp is the official Nemos command-line tool on npm (Node.js 20 or later). From a terminal or a script it signs in once with Apple, then searches and reads your library; every command takes --json for output a script can parse.

npm install -g nemos-mcp

nemos-mcp connect                 # sign in with Apple (once)
nemos-mcp search "ramen recipe"   # search everything you saved
nemos-mcp recent --limit 5        # what you saved lately
nemos-mcp get <item-id>           # one item in full
nemos-mcp folders                 # your folders
nemos-mcp status --json           # is this machine connected?

Run with no command, nemos-mcp is the MCP server for Claude Code, Cursor and other local hosts (nemos-mcp-http serves it over HTTP). Setup for each client, and the full list of tools, is on the MCP server page.

Authentication

The public endpoints need none. The MCP server uses OAuth 2.1: the authorization code flow with PKCE (S256), refresh tokens, and token revocation. Clients are public (no client secret) and identify themselves with an OAuth Client ID Metadata Document, so there is no API key to request and nothing to register by hand.

• Protected resource metadata (RFC 9728): https://mcp.nemosapp.com/.well-known/oauth-protected-resource/mcp
• Authorization server metadata (RFC 8414): https://mcp.nemosapp.com/.well-known/oauth-authorization-server
• Authorize: https://mcp.nemosapp.com/oauth/authorize · Token: https://mcp.nemosapp.com/oauth/token · Revoke: https://mcp.nemosapp.com/oauth/revoke

An unauthenticated call answers 401 with a WWW-Authenticate: Bearer header that names the metadata URL and the scope to ask for. Tool calls have per-account usage limits, listed on the MCP server page; past one, the server answers 429 with a Retry-After header.

Scopes

It is the only scope, so least privilege is the default: an agent cannot ask for more than reading. The scope is also declared in the OpenAPI security scheme and in the server's scopes_supported metadata.

Errors

Every failure under /api/ answers in JSON, in the RFC 9457 problem-details format (application/problem+json when you ask for it, application/json otherwise), with a stable code and a hint that says what to do next:

{
  "type": "https://nemosapp.com/developers/#error-not_found",
  "title": "Not found",
  "status": 404,
  "detail": "GET /api/nope failed with HTTP 404 (not found).",
  "instance": "/api/nope",
  "code": "not_found",
  "hint": "No endpoint matches this path. The endpoints this API serves are listed at https://nemosapp.com/openapi.json.",
  "docs": "https://nemosapp.com/openapi.json"
}

• bad_request (400): The request does not match the OpenAPI description.
• unauthorized (401): An OAuth access token is missing, expired or revoked. Run the authorization flow again.
• forbidden (403): The request is not allowed from this origin or account.
• not_found (404): No endpoint at this path. Check /openapi.json for the paths that exist.
• method_not_allowed (405): The path exists, but not for this HTTP method.
• not_acceptable (406): The Accept header asks for a format this URL cannot produce.
• rate_limited (429): Too many requests. Wait the seconds in the Retry-After header, then retry.
• internal_error (500): Something failed on our side. Retry later.
• unavailable (503): A dependency is down. /api/health shows which.

A page that does not exist answers 404 in the format you asked for: Markdown, JSON or HTML. The MCP server's own errors are JSON with an error code, such as {"error":"unauthorized"}.

Getting started

1. Read openapi.json or call /api/v1/health: no account, no key, no approval.
2. To read a library, install Nemos (free on the App Store, below) and save a few things.
3. Add https://mcp.nemosapp.com/mcp to your assistant and sign in when it asks.

There is no separate sandbox. The public endpoints are free, keyless and safe to call while you build. The MCP server only reads, and only the library of the account that signs in, so a free Nemos account with a few test items saved in it is a safe place to try your integration. There is nothing to pay for and no sales form to fill in.

Questions, or something missing that you need? Write to [email protected], or see the contact page.