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 mcp add gravity-index -- npx -y @gravity-ai/index-mcp

// 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"]
    }
  }
}

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

// Settings → Cascade → MCP servers
{
  "mcpServers": {
    "gravity-index": {
      "command": "npx",
      "args": ["-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.

# 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",
    "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 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
`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

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

export GRAVITY_PUBLISHER_KEY=your-publisher-api-key
gravity-index search "auth for Next.js"

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"}
  }'

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.

Start here

Provisioning

Explore

Interfaces

Partners

Install

MCP server (recommended)

One-liner install (npm)

Python alternative

Restart your agent

Test it

Bash CLI

Install

Use

Direct API

Publisher attribution

Troubleshooting

​MCP server (recommended)

​One-liner install (npm)

​Python alternative

​Restart your agent

​Test it

​Bash CLI

​Install

​Use

​Direct API

​Publisher attribution

​Troubleshooting

MCP server (recommended)

One-liner install (npm)

Python alternative

Restart your agent

Test it

Bash CLI

Install

Use

Direct API

Publisher attribution

Troubleshooting