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	30 sec
Terminal / shell scripts	Bash CLI	30 sec
Custom integration (your own agent)	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.

Claude Code

claude mcp add gravity-index -- npx -y @gravity-ai/index-mcp

Package: @gravity-ai/index-mcp · Source: sdk-js/packages/index-mcp

Python alternative

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

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

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

# 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

# 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.

# 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",
    "email_hash": "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 and /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
email_hash	string	Hash of the user’s normalized email, when available
metadata	object	Non-sensitive context such as surface, plan, workspace, or placement

MCP (npm)

{
  "mcpServers": {
    "gravity-index": {
      "command": "npx",
      "args": ["-y", "@gravity-ai/index-mcp"],
      "env": {
        "GRAVITY_PUBLISHER_KEY": "your-publisher-api-key"
      }
    }
  }
}

Get your publisher key →

---

Troubleshooting

`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.

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.

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.

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.