Skip to content
Open Gravity
Browse docsManual setup

Manual setup

Use these terminal commands to connect Claude Code or Codex yourself. To have your agent help with setup, copy the setup prompt.

Before you begin#

  • You need a Gravity account. Membership is by invitation, and connecting an agent can't create an account.
  • Sign in to Gravity in your default browser first, with the account you want your agent to use. If you aren't signed in, Gravity asks you to sign in during setup.

Claude Code#

  1. Add Gravity's server:

    bash
    claude mcp add --transport http --scope user gravity https://mcp.meetgravity.ai/api/mcp

    This makes Gravity available in every project. Use --scope local instead to limit it to the current project.

  2. Sign in:

    bash
    claude mcp login gravity

    You can also run /mcp inside Claude Code, choose gravity, then Authenticate.

  3. Your browser opens Gravity's consent screen. Check that it shows the right account, then choose Allow access.

  4. Confirm the connection:

    bash
    claude mcp list

  5. Open a new Claude Code session if Gravity’s tools aren’t available in your current one, then ask "What are my Gravity goals?"

Codex#

  1. Add Gravity's server:

    bash
    codex mcp add gravity --url https://mcp.meetgravity.ai/api/mcp

  2. Sign in:

    bash
    codex mcp login gravity

  3. Your browser opens Gravity's consent screen. Check that it shows the right account, then choose Allow access.

  4. Open a new Codex session if Gravity’s tools aren’t available in your current one, then ask "What are my Gravity goals?"

Other MCP clients#

Point your client at https://mcp.meetgravity.ai/api/mcp. The client needs to support:

  • remote servers over Streamable HTTP
  • the OAuth authorization code flow with PKCE (S256)
  • dynamic client registration
  • the OAuth resource parameter (RFC 8707)

Let the client handle sign-in so it can refresh its access. Don't paste an access token into its configuration. See Authentication for the details.

Troubleshooting#

What you seeWhat to do
The consent screen shows the wrong accountCancel. Sign in to the right Gravity account in your browser, then sign in from your client again. The connection uses your current browser sign-in.
"Connection not completed"The request expired, or your signed-in account changed. Start the sign-in from your client again with an existing Gravity account.
"Use S256 PKCE and the Gravity MCP resource URL."Your client didn't send PKCE or the resource parameter. Update the client to a version that supports MCP authorization.
"This connection supports the existing Gravity sign-in session and consent prompts."Your client asked for a fresh login or an account picker. Sign in to the right account in your browser, then connect again.
Your client says Gravity needs authentication againYour sign-in expired or was revoked. Run claude mcp login gravity or codex mcp login gravity again.

Next steps#