Skip to content
Browse docsManual setup

Manual setup

Connect Gravity to Claude, ChatGPT, or Codex. Choose your client below. In Claude Code or Codex CLI, you can also copy the setup prompt and ask your agent to help.

Before you begin#

  • You need an invited Gravity account. Connecting an agent cannot create an account.
  • Sign in to Gravity in your browser with the account you want your agent to use.
  • If Gravity is already connected in your client, reuse that connection. You do not need the Gravity plugin package to use its MCP tools.

Claude#

Claude Desktop, web, and mobile#

Add Gravity to your Claude account from Claude Desktop or the web. Use that account's connector across Claude apps, including mobile.

  1. Open Customize → Connectors.

  2. Choose Add, then Add custom connector. Name it Gravity and enter this server URL:

    text
    https://mcp.meetgravity.ai/api/mcp
    
  3. Continue through the detected OAuth settings. Choose Sign in now and keep Claude's recommended published identity. Gravity needs no API key or custom request headers.

  4. Finish adding the connector. If sign-in has not started, choose Connect beside Gravity.

  5. On Gravity's consent screen, check the account and choose Allow access.

  6. Start a new chat, enable Gravity in its connectors menu, and ask “What are my Gravity goals?”

On Team or Enterprise, an organization owner or an authorized administrator may need to add the connector before you connect your account. Claude's connector guide covers workspace permissions and current setup screens.

Claude Code#

If you added Gravity in Claude, Claude Code already has it when you sign in with that Claude account. Run /mcp and look for claude.ai Gravity. If it is connected, use it and skip the steps below. Adding Gravity again in Claude Code creates a separate connection that takes precedence over the connector and needs its own sign-in. See Claude Code's connector guidance.

If Gravity is not listed, or Claude Code does not use a Claude account sign-in, add it from your terminal:

  1. Add the server:

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

    User scope makes it available across projects. Use --scope local for only the current project.

  2. Authenticate:

    bash
    claude mcp login gravity
    
  3. Check the account on Gravity's consent screen and choose Allow access.

  4. Run claude mcp list, or /mcp inside Claude Code, to check the connection. Start a new session if the tools are missing, then ask “What are my Gravity goals?”

OpenAI#

ChatGPT#

Set up Gravity on the ChatGPT website. Install it for the account and workspace you use in ChatGPT, including the desktop app.

  1. Open ChatGPT Plugins.

  2. Choose +, then Add custom MCP server.

  3. Name it Gravity and enter this server URL under Connection:

    text
    https://mcp.meetgravity.ai/api/mcp
    
  4. Choose OAuth. Gravity does not require you to supply a client ID or secret. Review the connection notice and choose Create as a plugin.

  5. Install the resulting Gravity plugin and connect your account. On Gravity's consent screen, check the account and choose Allow access.

  6. Start a new chat, select Gravity with @ if needed, and ask “What are my Gravity goals?”

Your workspace controls whether you can add custom servers. See OpenAI's custom MCP setup if the option is unavailable.

Codex desktop#

For a direct Codex connection in OpenAI's desktop app:

  1. Open Settings → MCP servers, then choose Add server.

  2. Name the server gravity, choose Streamable HTTP, and enter:

    text
    https://mcp.meetgravity.ai/api/mcp
    
  3. Save the server and choose Restart. Select Authenticate when Gravity needs sign-in.

  4. On Gravity's consent screen, check the account and choose Allow access.

  5. Start a new Codex task and ask “What are my Gravity goals?” Use /mcp to inspect the connection.

This local configuration is shared with Codex CLI and the IDE extension on the same computer. If you already added Gravity there, reuse it. ChatGPT web uses the separate plugin setup above. See OpenAI's MCP guide.

Codex CLI#

Run codex mcp list first. If Gravity is already configured through the desktop app, CLI, or IDE extension, reuse that entry.

  1. Add the server if it is missing:

    bash
    codex mcp add gravity --url https://mcp.meetgravity.ai/api/mcp
    
  2. If the add command has not already completed sign-in, run:

    bash
    codex mcp login gravity
    
  3. On Gravity's consent screen, check the account and choose Allow access.

  4. Run codex mcp list to check the configuration. Open a new Codex session, use /mcp to check that Gravity is connected, and ask “What are my Gravity goals?”

Other MCP clients#

Point your client at https://mcp.meetgravity.ai/api/mcp. It needs Streamable HTTP, OAuth authorization code with S256 PKCE, client registration through a Client ID Metadata Document or dynamic registration, and the OAuth resource parameter.

Let the client handle sign-in and token refresh. Do not paste access tokens into its configuration. See Authentication for the details.

Troubleshooting#

What you seeWhat to do
Gravity is missing from a Claude chatStart a new chat and enable Gravity in its connectors menu. Check Customize → Connectors to confirm it is connected.
Gravity appears twice in Claude CodeCheck /mcp for an account connector and a direct entry. If you want the account connector, remove the direct entry with claude mcp remove gravity --scope user, using the scope where you added it.
Claude asks you to authenticate againChoose Connect in Claude's connector settings. For a direct Claude Code connection, use /mcp or claude mcp login gravity.
Codex asks you to authenticate againChoose Authenticate in the desktop app's MCP settings, or run codex mcp login gravity.
ChatGPT cannot use GravityCheck that the plugin is installed and connected in the current workspace. Start a new chat and select Gravity with @. Reconnect from Plugins if needed.
The command succeeded, but the tools are missingCheck /mcp in Claude Code or Codex, then start a new session. A saved server entry alone does not prove the connection works.
The consent screen shows the wrong accountCancel. Sign in to the right Gravity account in your browser, then connect again.
“Connection not completed”The request expired or your signed-in account changed. Start a fresh connection from your client.
“Use S256 PKCE and the Gravity MCP resource URL.”Your client omitted a required authorization parameter. Update it to a version that supports MCP authorization.
“This connection supports the existing Gravity sign-in session and consent prompts.”Connect while signed in to the intended Gravity account. If the error persists, the client is requesting a login mode Gravity does not support. Report the client and version; repeating sign-in will not fix an incompatible request.

Next steps#