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

# MCP Server

> AI agents call the Gravity Index natively

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.

<CodeGroup>
  ```json Claude Desktop theme={null}
  // ~/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"]
      }
    }
  }
  ```

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

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

### Required publisher key

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

```json theme={null}
{
  "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.

```bash theme={null}
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](/gravity-index/products)).

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.