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

# MCP Server

> AI agents call the Gravity Index natively

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

<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.ai \
  -- 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. Returns a reasoned recommendation with install instructions and a setup link.

| Parameter               | Type   | Required | Description                                                                          |
| ----------------------- | ------ | -------- | ------------------------------------------------------------------------------------ |
| `query`                 | string | Yes      | What you need — e.g. `"serverless database with free tier"`                          |
| `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 agent finishes an install. 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.