> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trygravity.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Install

> Get the Gravity Index working in your agent, editor, or terminal in 60 seconds

# Install

Pick the surface that fits how you code.

| You use…                                                                  | Install                                     | Time   |
| ------------------------------------------------------------------------- | ------------------------------------------- | ------ |
| **AI coding agent** (Cursor, Claude Code, Claude Desktop, Windsurf, etc.) | [MCP server → npm](#mcp-server-recommended) | 30 sec |
| **Terminal / shell scripts**                                              | [Bash CLI](#bash-cli)                       | 30 sec |
| **Custom integration** (your own agent)                                   | [Direct API](#direct-api)                   | —      |

Production calls require a publisher key so searches, setup links, and completed integrations attribute back to the embedding platform. If you're evaluating the Index, ask Gravity for a publisher key first.

***

## MCP server (recommended)

The Gravity Index ships as an MCP server so your agent can call it as a native tool — no HTTP client code, no prompt engineering.

### One-liner install (npm)

The npm wrapper is zero-dependency and runs via `npx`. No Python, no clone, no build.

<CodeGroup>
  ```bash Claude Code theme={null}
  claude mcp add gravity-index -- npx -y @gravity-ai/index-mcp
  ```

  ```json Claude Desktop theme={null}
  // macOS:   ~/Library/Application Support/Claude/claude_desktop_config.json
  // Windows: %APPDATA%\Claude\claude_desktop_config.json
  {
    "mcpServers": {
      "gravity-index": {
        "command": "npx",
        "args": ["-y", "@gravity-ai/index-mcp"]
      }
    }
  }
  ```

  ```json Cursor theme={null}
  // Settings → MCP → Add new MCP server
  {
    "mcpServers": {
      "gravity-index": {
        "command": "npx",
        "args": ["-y", "@gravity-ai/index-mcp"]
      }
    }
  }
  ```

  ```json Windsurf theme={null}
  // Settings → Cascade → MCP servers
  {
    "mcpServers": {
      "gravity-index": {
        "command": "npx",
        "args": ["-y", "@gravity-ai/index-mcp"]
      }
    }
  }
  ```
</CodeGroup>

Package: [`@gravity-ai/index-mcp`](https://www.npmjs.com/package/@gravity-ai/index-mcp) · Source: [`sdk-js/packages/index-mcp`](https://github.com/Try-Gravity/gravity/tree/main/sdk-js/packages/index-mcp)

### Python alternative

If you already have `uv` / Python 3.12 and prefer to run from source:

```bash theme={null}
git clone https://github.com/Try-Gravity/gravity.git
cd gravity

claude mcp add gravity-index \
  -e GRAVITY_INDEX_URL=https://index.trygravity.ai \
  -- uv run index/mcp/gravity_index_mcp.py
```

Source: [`index/mcp/gravity_index_mcp.py`](https://github.com/Try-Gravity/gravity/tree/main/index/mcp)

### Restart your agent

After adding the server, restart Cursor / Claude / Windsurf. You should see 5 new tools:

* `gravity_index_search` — LLM-driven "I need X" query
* `gravity_index_browse` — list services, filter by category, tag search
* `gravity_index_list_categories` — enumerate all 22 categories with counts
* `gravity_index_get_service` — deep lookup by slug
* `gravity_index_report_integration` — tell the Index a user finished an integration

### Test it

Ask your agent something like: *"I need to add email sending to my Next.js app — search the Gravity Index for options."*

***

## Bash CLI

Search the Index from your terminal. Useful for shell scripts, CI, or quick ad-hoc queries. The standalone CLI currently ships from the Gravity repo, so use this path if you have repo access; public agent integrations should use the npm MCP server above.

### Install

```bash theme={null}
# From a local Gravity checkout:
cd gravity
mkdir -p ~/.local/bin
cp index/cli/gravity-index ~/.local/bin/gravity-index
chmod +x ~/.local/bin/gravity-index

# Make sure ~/.local/bin is on PATH (add to ~/.zshrc or ~/.bashrc):
export PATH="$HOME/.local/bin:$PATH"

# One-time dependency (the CLI uses httpx for HTTP)
pip install --user httpx
# or:
uv tool install httpx
```

Requires Python 3.9+.

### Use

```bash theme={null}
# Search
gravity-index search "I need a serverless database"

# Search with publisher identity metadata for attribution/matching
gravity-index search "I need a serverless database" \
  --external-session-id session_123 \
  --external-user-id-hash sha256_user_id \
  --email-hash sha256_email \
  --metadata-json '{"surface":"chat"}'

# Browse
gravity-index browse
gravity-index browse --category Database
gravity-index browse "vector"

# Lookup
gravity-index info supabase
```

Returns color-formatted terminal output with the recommendation, reasoning, install steps, env vars needed, and a conversion URL.

***

## Direct API

If you're building your own agent or want to call the Index from any language, it's a plain REST API at `https://index.trygravity.ai`.

```bash theme={null}
# Health
curl https://index.trygravity.ai/health

# Search
curl -X POST https://index.trygravity.ai/search \
  -H 'content-type: application/json' \
  -H "X-API-Key: $GRAVITY_PUBLISHER_KEY" \
  -d '{
    "query": "I need a transactional email API for AI agents",
    "external_session_id": "session_123",
    "external_user_id_hash": "sha256_user_id",
    "hashed_email": "sha256_email",
    "metadata": {"surface": "chat"}
  }'

# Browse
curl -H "X-API-Key: $GRAVITY_PUBLISHER_KEY" 'https://index.trygravity.ai/services'
curl -H "X-API-Key: $GRAVITY_PUBLISHER_KEY" 'https://index.trygravity.ai/categories'
curl -H "X-API-Key: $GRAVITY_PUBLISHER_KEY" 'https://index.trygravity.ai/services/supabase'
```

Full API reference: [/gravity-index/search](/gravity-index/search) and [/gravity-index/catalog](/gravity-index/catalog).

***

## Publisher attribution

If you're a platform publisher embedding the Gravity Index in your own AI app, set a `GRAVITY_PUBLISHER_KEY` so requests and completed integrations from your users attribute to your account.

For best attribution and payout matching, send stable per-user/session metadata on every `/search` call:

| Field                   | Type   | Notes                                                                                                  |
| ----------------------- | ------ | ------------------------------------------------------------------------------------------------------ |
| `external_session_id`   | string | Your stable chat/session ID                                                                            |
| `external_user_id_hash` | string | Hash of your user ID; preferred over raw IDs                                                           |
| `external_user_id`      | string | Optional raw user ID; Gravity stores only a SHA-256 hash                                               |
| `hashed_email`          | string | SHA-256 of the user's normalized email, when available (canonical; legacy `email_hash` still accepted) |
| `metadata`              | object | Non-sensitive context such as surface, plan, workspace, or placement                                   |

<CodeGroup>
  ```json MCP (npm) theme={null}
  {
    "mcpServers": {
      "gravity-index": {
        "command": "npx",
        "args": ["-y", "@gravity-ai/index-mcp"],
        "env": {
          "GRAVITY_PUBLISHER_KEY": "your-publisher-api-key"
        }
      }
    }
  }
  ```

  ```bash CLI theme={null}
  export GRAVITY_PUBLISHER_KEY=your-publisher-api-key
  gravity-index search "auth for Next.js"
  ```

  ```bash Direct API theme={null}
  curl -X POST https://index.trygravity.ai/search \
    -H 'content-type: application/json' \
    -H 'X-API-Key: your-publisher-api-key' \
    -d '{
      "query": "...",
      "external_session_id": "session_123",
      "external_user_id_hash": "sha256_user_id",
      "hashed_email": "sha256_email",
      "metadata": {"surface": "chat"}
    }'
  ```
</CodeGroup>

[Get your publisher key →](/gravity-index/for-service-providers)

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="`npx` fails with `ENOENT` or cannot find package">
    Make sure you have Node 18+ installed: `node -v`. Then try a manual pre-install: `npm install -g @gravity-ai/index-mcp && which gravity-index-mcp`.

    If that works, replace the `npx` command in your config with the absolute path.
  </Accordion>

  <Accordion title="MCP tools don't show up after restart">
    Check the MCP server logs:

    * **Claude Desktop**: `~/Library/Logs/Claude/mcp*.log` (macOS)
    * **Cursor**: Settings → MCP → check status next to `gravity-index`
    * **Claude Code**: `claude mcp list` to see running servers

    Most common cause: `npx` can't reach the npm registry. Test with `npx -y @gravity-ai/index-mcp --help` in a terminal.
  </Accordion>

  <Accordion title="CLI says `httpx: No module named`">
    The CLI needs `httpx`. Install it with `pip install --user httpx` or, if you use `uv`, `uv tool install httpx`.
  </Accordion>

  <Accordion title="Search is slow / times out">
    The `/search` endpoint uses an LLM to pick the best service — cold starts can take 2–4 seconds. Subsequent queries within a session are usually \< 1s. If you're seeing consistent timeouts, check `https://index.trygravity.ai/health` and open an issue at [github.com/Try-Gravity/gravity/issues](https://github.com/Try-Gravity/gravity/issues).
  </Accordion>
</AccordionGroup>