# Gravity API and developer docs

> Reach Gravity notes from code. The Gravity API is an MCP server with OAuth sign-in, plus a command-line tool for the Mac. Free, self-serve, no API keys.

Canonical: https://www.gravitynotes.app/developers

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

| | [Gravity MCP server](https://www.gravitynotes.app/mcp) | [Gravity CLI](https://www.gravitynotes.app/notes-app-for-ai-agents) |
|---|---|---|
| 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](https://www.gravitynotes.app/mcp) 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](https://www.gravitynotes.app/connect-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](https://www.gravitynotes.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:

```sh
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](https://www.gravitynotes.app/notes-app-for-ai-agents) covers every command and how it keeps notes safe. The Homebrew formula is on [GitHub](https://github.com/tristanmanchester/homebrew-tap).

## Machine-readable discovery

| What | Where |
|---|---|
| API catalog (RFC 9727) | [/.well-known/api-catalog](https://www.gravitynotes.app/.well-known/api-catalog) |
| MCP Server Card | [mcp.gravitynotes.app/mcp/server-card](https://mcp.gravitynotes.app/mcp/server-card) |
| OAuth protected resource metadata (RFC 9728) | [mcp.gravitynotes.app/.well-known/oauth-protected-resource/mcp](https://mcp.gravitynotes.app/.well-known/oauth-protected-resource/mcp) |
| OAuth authorization server metadata (RFC 8414) | [mcp.gravitynotes.app/.well-known/oauth-authorization-server](https://mcp.gravitynotes.app/.well-known/oauth-authorization-server) |
| Agent registration | [/auth.md](https://www.gravitynotes.app/auth.md) |
| AI catalog | [/.well-known/ai-catalog.json](https://www.gravitynotes.app/.well-known/ai-catalog.json) |
| Agent skill for the CLI | [/.well-known/agent-skills/index.json](https://www.gravitynotes.app/.well-known/agent-skills/index.json) |
| Site index for LLMs | [/llms.txt](https://www.gravitynotes.app/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](https://www.gravitynotes.app/changelog). Questions, bugs or a use case Gravity doesn't cover yet: email [tristan@crowlabs.co](mailto:tristan@crowlabs.co).