# Gravity MCP server

> Reference for the Gravity MCP server at mcp.gravitynotes.app/mcp. Its 14 tools, OAuth sign-in, protocol versions and limits, for developers and AI agents.

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

The Gravity MCP server lets AI apps and agents read and change a person's Gravity notes. It's Gravity's API, and it works with any client that speaks the Model Context Protocol.

```
https://mcp.gravitynotes.app/mcp
```

| | |
|---|---|
| Transport | Streamable HTTP, stateless |
| Protocol versions | 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05 |
| Sign-in | OAuth 2.1 with PKCE; see [auth.md](https://www.gravitynotes.app/auth.md) |
| Price | Free with Gravity Sync, which is free during the beta |
| Registry name | `app.gravitynotes/gravity` |
| Server Card | [mcp.gravitynotes.app/mcp/server-card](https://mcp.gravitynotes.app/mcp/server-card) |

To add it to Claude, ChatGPT, Codex or Grok, follow [Connect Gravity to your AI apps](https://www.gravitynotes.app/connect-ai-apps). In Claude Code:

```
claude mcp add --transport http gravity https://mcp.gravitynotes.app/mcp
```

## Tools

| Tool | What it does |
|---|---|
| `search` | Finds notes by words, the way app search does. `todo: dentist` filters by tag. |
| `fetch` | Returns one note's full text. Long notes come in 60,000-character parts. |
| `list_notes` | Lists notes by order, tag, state, creation date and optional words, with a cursor. |
| `list_tags` | Lists tags with how many notes use each. |
| `add_note` | Adds a note at the top, with an optional tag. A `request_id` makes retries safe. |
| `append_to_note` | Adds a paragraph to the end of a note. |
| `edit_note` | Replaces one exact quoted piece of a note's current text. |
| `rescue_note` | Moves a note back to the top and unarchives it. |
| `archive_note` | Moves a note to Archive. |
| `restore_note` | Brings a note back from Deleted Notes. |
| `trash_note` | Moves a note to Deleted Notes. |
| `upload_audio` | Returns a signed link to upload a recording of up to 100 MB. |
| `transcribe_audio` | Turns speech in a recording into text, in 99 languages. |
| `add_voice_note` | Transcribes a recording and saves it as a new note. A spoken tag ("To do, …") becomes the note's tag. |

Every tool has a title, read-only, destructive, idempotent and open-world hints, and an output schema. Nothing deletes a note permanently.

## Sign-in and scopes

An unauthenticated call returns `401` with a `WWW-Authenticate` header pointing at the [protected resource metadata](https://mcp.gravitynotes.app/.well-known/oauth-protected-resource/mcp). From there a client finds the [authorization server metadata](https://mcp.gravitynotes.app/.well-known/oauth-authorization-server) and registers itself with a client ID metadata document or dynamic client registration. Most MCP clients do all of this for you.

- `notes:read` covers searching, listing and reading.
- `notes:write` covers every change. A read-only connection that tries a write gets a step-up challenge.
- `offline_access` adds a refresh token.

The person approving the connection needs Gravity Sync turned on in a Gravity app, on iPhone, iPad, Mac or Android. They can disconnect any app in Gravity under **Settings → Gravity Sync → AI apps**.

## Limits

- 120 reads and 60 writes a minute for each connected app.
- 4 MiB for one request. Send bigger recordings through `upload_audio`.
- Access tokens last an hour. Refresh tokens rotate and last 60 days without use.

## Privacy

Notes an AI app reads go to that app's provider under their terms. Gravity keeps a record of which connected app changed which note, never the note text, for 90 days. Uploaded recordings are deleted once they're transcribed, and within two days at most. The [privacy policy](https://www.gravitynotes.app/privacy-policy#ai-apps) has the details.

More: [Gravity API docs](https://www.gravitynotes.app/developers) · [changelog](https://www.gravitynotes.app/changelog) · [tristan@crowlabs.co](mailto:tristan@crowlabs.co)