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.
-
Open Customize → Connectors.
-
Choose Add, then Add custom connector. Name it
Gravityand enter this server URL:texthttps://mcp.meetgravity.ai/api/mcp -
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.
-
Finish adding the connector. If sign-in has not started, choose Connect beside Gravity.
-
On Gravity's consent screen, check the account and choose Allow access.
-
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:
-
Add the server:
bashclaude mcp add --transport http --scope user gravity https://mcp.meetgravity.ai/api/mcpUser scope makes it available across projects. Use
--scope localfor only the current project. -
Authenticate:
bashclaude mcp login gravity -
Check the account on Gravity's consent screen and choose Allow access.
-
Run
claude mcp list, or/mcpinside 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.
-
Open ChatGPT Plugins.
-
Choose +, then Add custom MCP server.
-
Name it
Gravityand enter this server URL under Connection:texthttps://mcp.meetgravity.ai/api/mcp -
Choose OAuth. Gravity does not require you to supply a client ID or secret. Review the connection notice and choose Create as a plugin.
-
Install the resulting Gravity plugin and connect your account. On Gravity's consent screen, check the account and choose Allow access.
-
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:
-
Open Settings → MCP servers, then choose Add server.
-
Name the server
gravity, choose Streamable HTTP, and enter:texthttps://mcp.meetgravity.ai/api/mcp -
Save the server and choose Restart. Select Authenticate when Gravity needs sign-in.
-
On Gravity's consent screen, check the account and choose Allow access.
-
Start a new Codex task and ask “What are my Gravity goals?” Use
/mcpto 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.
-
Add the server if it is missing:
bashcodex mcp add gravity --url https://mcp.meetgravity.ai/api/mcp -
If the add command has not already completed sign-in, run:
bashcodex mcp login gravity -
On Gravity's consent screen, check the account and choose Allow access.
-
Run
codex mcp listto check the configuration. Open a new Codex session, use/mcpto 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 see | What to do |
|---|---|
| Gravity is missing from a Claude chat | Start a new chat and enable Gravity in its connectors menu. Check Customize → Connectors to confirm it is connected. |
| Gravity appears twice in Claude Code | Check /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 again | Choose Connect in Claude's connector settings. For a direct Claude Code connection, use /mcp or claude mcp login gravity. |
| Codex asks you to authenticate again | Choose Authenticate in the desktop app's MCP settings, or run codex mcp login gravity. |
| ChatGPT cannot use Gravity | Check 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 missing | Check /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 account | Cancel. 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#
- Learn how sign-in and permissions work.
- Read about goals and audiences.
- Try a guide: find matches and search again.