Browse docsAuthentication

Authentication

Your agent acts as you, with your permission. It signs in through OAuth: you approve the connection once in your browser, and your client keeps it working after that.

Your client calls https://mcp.meetgravity.ai/api/mcp without a token and gets 401 Unauthorized. The response's WWW-Authenticate header points to Gravity's protected resource metadata.
The client reads that metadata and finds Gravity's authorization server. Gravity supports hosted Client ID Metadata Documents (CIMD), and retains dynamic registration for clients that use it.
Your browser opens Gravity's consent screen, signed in as you. You choose Allow access.
The client receives tokens and sends Authorization: Bearer <access token> with every request.

MCP clients that support authorization do all of this for you.

Endpoints#

Document	URL
Protected resource metadata (RFC 9728)	`https://mcp.meetgravity.ai/.well-known/oauth-protected-resource/api/mcp`
Authorization server metadata (RFC 8414)	`https://mcp.meetgravity.ai/.well-known/oauth-authorization-server/api/oauth`

Property	Value
Issuer	`https://mcp.meetgravity.ai/api/oauth`
Resource (token audience)	`https://mcp.meetgravity.ai/api/mcp`
Grant types	`authorization_code`, `refresh_token`
PKCE	Required, `S256` only
`resource` parameter	Required when authorizing, and must equal the resource above
Client registration	CIMD with the MCP metadata profile, or dynamic client registration. Native clients use loopback redirect URIs on `localhost`, `127.0.0.1`, or `[::1]`.
CIMD client authentication	Public clients use `none` with PKCE. Clients with signing keys may use `private_key_jwt`.
Access tokens	Opaque bearer tokens, valid for 1 hour, sent in the `Authorization` header
Refresh tokens	Issued with `offline_access`, valid until 90 days without use
`prompt` and `max_age`	`prompt=consent` is supported. `prompt=login`, `prompt=create`, `prompt=select_account`, and `max_age` aren't, because the connection uses your existing browser sign-in.

Permissions#

Scope	Requested by default	What it allows
`gravity:read`	Yes	Read your accessible groups, rosters, goals, private goal details, saved matches, and your own Rolodex identities, profile sections, and private person notes through Gravity's privacy rules.
`gravity:edit`	Yes	Save, change, share, or end goals, start matching searches, and add, correct, or forget your private person notes when you request them.
`offline_access`	Client choice	Obtain refresh tokens to stay connected between sessions. This is an authorization-server scope, not an MCP resource requirement.

The normal connection requests read and edit together up front. A client can deliberately request read-only access; Gravity accepts it and rejects writes before any changes or searches. Consent describes only the permissions requested. Routine features within these capabilities do not require another consent prompt. Permission to edit still requires your request for an individual change, and your client's approval policy also applies.

Gravity advertises offline_access in authorization-server metadata only. Clients that want refresh tokens should request it along with their resource scopes. A request without an explicit scope uses the registered client's default scopes, which include read, edit, and offline access for new clients.

Read permission includes finding people in your own Rolodex and reading their private notes. Edit permission includes adding, correcting, and explicitly forgetting those notes when you ask. No permission lets an agent browse another member’s Rolodex, see contact details for people found through other members, or contact anyone.

The consent screen shows the app asking for access and the Gravity account you're signed in as, then lists what the connection allows. Choose Allow access to connect, or Cancel to refuse.

Only approve a connection you started yourself. The app supplies its name and optional HTTPS logo. Gravity uses a generic icon when the logo is missing or unusable. CIMD connections show their metadata domain; other connections may show a website labeled as supplied by the app. A name, logo, or supplied website is not a verification badge.

Staying connected#

Access tokens last an hour. Your client refreshes them automatically, so you won't notice. If the refresh fails, for example after 90 days without use, your client asks you to sign in again.

Each request is checked on its own. Gravity confirms the token is active, was issued by Gravity for this server, and belongs to a current member. Tool calls require their read or edit permission. Your agent always acts as the account that approved it. Tool arguments can't change that.

If a connection can no longer refresh or sign in, remove Gravity from your MCP client and add it again. This lets the client register or discover its identity again and request the current permissions.

Disconnecting#

In Gravity, open Profile → Connectors to see your connected agents and their permissions. Choose Disconnect to end an agent's access, including its refresh tokens. It will need your consent again to reconnect. Gmail and LinkedIn stay under Sources.

Claude Code: claude mcp logout gravity signs out. claude mcp remove gravity removes the server and its sign-in.
Codex and other clients: remove the server or sign out in the client.

Signing out in a client deletes its tokens on that device; use Gravity's Disconnect control to end the server-side grant. Gravity's revocation endpoint, https://mcp.meetgravity.ai/api/oauth/oauth2/revoke, also revokes a token when the client calls it. A token that wasn't revoked stops working when it expires.

Leaving Gravity ends every agent's access immediately.

Errors#

Response	Meaning	What to do
`401` with `WWW-Authenticate`	No token, or the token expired or was revoked	Let your client refresh, or sign in again.
`403` with `error="insufficient_scope"`	The token lacks permission for this operation	Continue reading with a read-only connection, or authorize the scopes in the challenge if you want the additional capability.
`429` with `Retry-After`	The connection exceeded the member's read or write limit	Wait for the indicated delay before retrying.
`503`	Gravity's sign-in service is temporarily unavailable	Try again later.