Gravity API and developer docs

Gravity is a notes app with one list. Code reaches those notes in two ways:

	Gravity MCP server	Gravity CLI
Reads and writes	The person's Gravity Sync library, on every device	Notes in the Gravity Mac app
Runs	At https://mcp.gravitynotes.app/mcp, over HTTPS	On the person's Mac
Sign-in	OAuth 2.1: the person approves your app	None: it reads the local library
Best for	AI apps, agents and hosted services	Scripts and agents on the same Mac

Free and self-serve

Gravity Sync is free during the beta, and the MCP server and the CLI cost nothing on top. There are no API keys to request, no waitlist and no sales call. Register an OAuth client yourself, or install the CLI with Homebrew, and start.

The Gravity MCP server

The MCP server is Gravity's API. Any MCP client can call it over Streamable HTTP:

https://mcp.gravitynotes.app/mcp

It has 14 tools: search, fetch, list notes and tags, add, append, edit, rescue, archive, restore, trash, and transcribe or save voice notes. The MCP server reference lists each tool, the protocol versions it serves and its limits. To add it to Claude, ChatGPT, Codex or Grok, see Connect Gravity to your AI apps.

Authentication

Every call needs a bearer token for one person's library, issued by Gravity's OAuth server at https://mcp.gravitynotes.app:

1. Register: use a client ID metadata document URL as your client_id, or POST /oauth/register (RFC 7591).
2. Send the person to /authorize with PKCE (S256) and resource=https://mcp.gravitynotes.app/mcp. They choose read-only or read and write, then sign in with Apple, Google or an email code.
3. Exchange the code at /oauth/token, then send Authorization: Bearer <token>.

Scopes are notes:read, notes:write and offline_access. Access tokens last an hour; refresh tokens rotate and last 60 days without use. The person needs Gravity Sync turned on in a Gravity app. auth.md walks an agent through the whole flow.

Limits

• 120 reads and 60 writes a minute for each connected app.
• 4 MiB for one request. Recordings up to 100 MB go through upload_audio.
• No permanent delete, bulk change or import. Trashed notes stay in Deleted Notes, where the person can restore them.

The Gravity CLI

On a Mac with the Gravity app:

brew install tristanmanchester/tap/gravity-cli
gravity doctor
gravity agent

gravity agent prints a guide written for agents. Add --json to any command for structured output. The Gravity CLI guide covers every command and how it keeps notes safe. The Homebrew formula is on GitHub.

Machine-readable discovery

What	Where
API catalog (RFC 9727)	/.well-known/api-catalog
MCP Server Card	mcp.gravitynotes.app/mcp/server-card
OAuth protected resource metadata (RFC 9728)	mcp.gravitynotes.app/.well-known/oauth-protected-resource/mcp
OAuth authorization server metadata (RFC 8414)	mcp.gravitynotes.app/.well-known/oauth-authorization-server
Agent registration	/auth.md
AI catalog	/.well-known/ai-catalog.json
Agent skill for the CLI	/.well-known/agent-skills/index.json
Site index for LLMs	/llms.txt
DNS-AID	_mcp._agents.gravitynotes.app and _index._agents.gravitynotes.app (SVCB)
MCP Registry	app.gravitynotes/gravity

Every page on this site is also available as Markdown: add .md to the URL or send Accept: text/markdown.

Changes and help

Releases of the MCP server and the CLI are in the changelog. Questions, bugs or a use case Gravity doesn't cover yet: email tristan@crowlabs.co.