# Quickstart

Connect Claude Code or Codex to Gravity, then ask about your goals.

## 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 gravity https://www.meetgravity.ai/api/mcp
   ```

   This adds Gravity to the current project. Add `--scope user` to use it in every 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. Ask Claude Code something like "What are my Gravity goals?"

## Codex

1. Add Gravity's server:

   ```bash
   codex mcp add gravity --url https://www.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. Ask Codex something like "What are my Gravity goals?"

## Other MCP clients

Point your client at `https://www.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](/docs/mcp/authentication) for the details.

## Troubleshooting

| What you see | What to do |
| --- | --- |
| The consent screen shows the wrong account | Cancel. 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 again | Your sign-in expired or was revoked. Run `claude mcp login gravity` or `codex mcp login gravity` again. |

## Next steps

- Learn how [sign-in and permissions](/docs/mcp/authentication) work.
- See [what each tool does](/docs/mcp/tools).
- Try a guide: [find matches and search again](/docs/mcp/guides/find-matches).