MCP Server

The Gravity Index ships as an MCP server so AI coding agents can call it as a native tool — no HTTP client code needed.

Install (recommended: npm)

One-liner — no Python, no clone, no build.

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

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

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

Required publisher key

Pass your publisher key so Index requests and completed integrations attribute to your platform:

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

Optional private ranking is configured with GRAVITY_INDEX_MONETIZATION_MODE=boost_cpa — relevance-first ranking that gives a small boost to services with an active CPA campaign. MCP tool output does not expose economics.

Install (Python, for self-hosted setups)

The reference implementation lives in the Gravity monorepo at index/mcp/gravity_index_mcp.py. Exposes the same tools, identical behaviour.

claude mcp add gravity-index \
  -e GRAVITY_INDEX_URL=https://index.trygravity.com \
  -- python3 /path/to/gravity_index_mcp.py

Tools

Five tools. All return plain-text markdown the agent can display directly.

`gravity_index_search`

Search for the best tool for a development task, or (with vertical: "consumer") the best retail product. Developer results are a reasoned recommendation with a tracked signup link; consumer results are products with merchant, price, image and a buy link (see Product search).

Parameter	Type	Required	Description
`query`	string	Yes	What you need, e.g. `"serverless database with free tier"` or `"men's Nike running shoes"`
`vertical`	string	No	`developer` (default), `consumer`, or `auto` to let the Index route
`filters`	object	No	Consumer hard filters: `brands[]`, `merchants[]`, `price_min`, `price_max`, `currency`, `sizes[]`, `colors[]`, `gender`, `categories[]`, `on_sale_only`
`search_id`	string	No	Continue a previous search (follow-up)
`context`	object	No	Framework/language/runtime/package manager constraints
`external_session_id`	string	No	Publisher session ID for attribution and matching
`external_user_id_hash`	string	No	Hashed publisher user ID
`hashed_email`	string	No	SHA-256 of the normalized user email (canonical; legacy `email_hash` still accepted)
`metadata`	object	No	Non-sensitive publisher metadata stored with the search

Example:

User:  "I need a database for my project."
Agent: gravity_index_search({ query: "database" })
       → "I recommend Neon — serverless Postgres with a free tier.
          1. npm install @neondatabase/serverless
          2. Create lib/db.ts
          3. Open the tracked setup link, get DATABASE_URL, and paste it back so I can finish"

`gravity_index_browse`

Browse the catalog by category or keyword.

Parameter	Type	Required	Description
`category`	string	No	Filter by category
`q`	string	No	Search keyword

`gravity_index_get_service`

Fetch the full detail for a single service by slug.

Parameter	Type	Required	Description
`slug`	string	Yes	e.g. `"supabase"`

`gravity_index_list_categories`

Enumerate every category with the service count. Takes no arguments.

`gravity_index_report_integration`

Record a completed integration when the user has adopted the recommended service. Accepts the search_id from a prior search and the slug of the service that was actually integrated.

Parameter	Type	Required	Description
`search_id`	string	Yes	From a previous `gravity_index_search`
`integrated_slug`	string	Yes	e.g. `"stripe"`

Zero dependencies

The npm server is a single Node 18+ .mjs file with no runtime deps. The Python server is stdlib-only.

Start here

Interfaces

Partners

Install (recommended: npm)

Required publisher key

Install (Python, for self-hosted setups)

Tools

`gravity_index_search`

`gravity_index_browse`

`gravity_index_get_service`

`gravity_index_list_categories`

`gravity_index_report_integration`

Zero dependencies

​Install (recommended: npm)

​Required publisher key

​Install (Python, for self-hosted setups)

​Tools

​gravity_index_search

​gravity_index_browse

​gravity_index_get_service

​gravity_index_list_categories

​gravity_index_report_integration

​Zero dependencies

Install (recommended: npm)

Required publisher key

Install (Python, for self-hosted setups)

Tools

`gravity_index_search`

`gravity_index_browse`

`gravity_index_get_service`

`gravity_index_list_categories`

`gravity_index_report_integration`

Zero dependencies