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://www.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, finds Gravity's authorization server, and registers itself.
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://www.meetgravity.ai/.well-known/oauth-protected-resource/api/mcp`
Authorization server metadata (RFC 8414)	`https://www.meetgravity.ai/.well-known/oauth-authorization-server/api/oauth`

Property	Value
Issuer	`https://www.meetgravity.ai/api/oauth`
Resource (token audience)	`https://www.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	Dynamic client registration. Native clients use loopback redirect URIs on `localhost`, `127.0.0.1`, or `[::1]`.
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	Required	What it allows
`matching:manage`	Yes	Everything the tools do: reading your groups, rosters, goals, and matches, saving goals, and starting searches.
`offline_access`	No	Staying connected without signing in again every hour.

There's no read-only connection yet. matching:manage covers reading and writing together, so a connected agent can save goals and start searches. Most MCP clients, including Claude Code, ask you before running a tool unless you've allowed it, so approve changes only when you meant to make them.

No permission lets an agent browse your 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 name on the consent screen is the name the app gave itself.

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, carries matching:manage, and belongs to a current member. Your agent always acts as the account that approved it. Tool arguments can't change that.

Disconnecting#

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. Gravity's revocation endpoint, https://www.meetgravity.ai/api/oauth/oauth2/revoke, revokes a token when the client calls it. You can't see or revoke connected agents from Gravity yet. 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 doesn't include `matching:manage`	Sign in again and approve the connection.
`503`	Gravity's sign-in service is temporarily unavailable	Try again later.