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.

Claude Desktop

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

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 modes are configured with GRAVITY_INDEX_MONETIZATION_MODE=boost_cpa, cpa_only, or cpa_desc. 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.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
email_hash	string	No	Hashed normalized user email
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.