Skip to main content
This page tells you how to connect the Gravity Index to your agent, your editor, or your terminal. Select the interface that fits your work.

Before you start

  • Get a Gravity publisher API key. Every Index call needs it. Without a key, the Index returns 401. To get a key, contact Gravity at index@trygravity.ai.
  • For the MCP server, install Node.js 18 or later.
  • For the CLI, install Python 3 and the httpx package.
In the examples, replace YOUR_API_KEY with your publisher API key.
The Gravity Index MCP server gives your agent the Index as a set of tools. Your agent can call the tools directly. You do not write HTTP client code. The Gravity Index MCP server is not the Gravity dashboard MCP server for advertisers and publishers. It is a separate product.

Add the server (npm)

The npm package @gravity-ai/index-mcp has no dependencies. npx downloads and runs it. You do not need Python, a clone, or a build step. Add the server to your client. Put your key in GRAVITY_PUBLISHER_KEY.
Source: sdk-js/packages/index-mcp

Run the Python server from source (optional)

If you have access to the Gravity repository, you can run the Python version of the server. It uses only the Python standard library. It has more tools than the npm server. See MCP server for the differences.
Source: index/mcp/gravity_index_mcp.py

Restart your agent

Restart Cursor, Claude, or Windsurf after you add the server. The npm server adds five tools:
  • gravity_index_search: find the best service for a request, for example “I need a database”.
  • gravity_index_browse: list services. Filter by category or by keyword.
  • gravity_index_list_categories: list all categories, with the number of services in each.
  • gravity_index_get_service: get the full details of one service by its slug.
  • gravity_index_report_integration: tell the Index that the user finished an integration.

Test the server

Ask your agent: “I need to add email sending to my Next.js app. Search the Gravity Index for options.” The agent calls gravity_index_search. You see a recommendation, the reasons for it, and a setup link.

Bash CLI

The CLI lets you search the Index from a terminal, a shell script, or a CI job. The CLI is in the Gravity repository and is not on a package registry. Use it only if you have repository access. For public agent integrations, use the npm MCP server.

Install the CLI

  1. Go to your local copy of the Gravity repository.
  2. Copy the script to a folder on your PATH.
  3. Make sure that ~/.local/bin is on your PATH. Add this line to ~/.zshrc or ~/.bashrc:
  4. Install httpx. The CLI uses it for HTTP calls.
  5. Set your publisher API key.

Use the CLI

The CLI prints color output with the recommendation, the reasons, and a tracked setup link. See CLI for all commands and flags.

Direct API

To call the Index from your own agent or from any language, use the REST API at https://index.trygravity.com.
The health check returns {"status": "ok", "service": "gravity-index"}. For the full reference, see Search and Product search.

Publisher attribution

Gravity uses your publisher API key to attribute searches, clicks, and completed integrations to your account. For better attribution, send stable identity fields on every /search call: The MCP server and the CLI send the key from GRAVITY_PUBLISHER_KEY for you. The MCP server and the CLI send the email hash as email_hash.

Troubleshoot

  1. Make sure that Node.js 18 or later is on your machine: node -v.
  2. Install the package globally: npm install -g @gravity-ai/index-mcp.
  3. Find the binary: which gravity-index-mcp.
  4. In your MCP config, replace the npx command with the absolute path from step 3.
Look at the MCP server status or logs:
  • Claude Desktop: ~/Library/Logs/Claude/mcp*.log (macOS).
  • Cursor: Settings > MCP. Look at the status next to gravity-index.
  • Claude Code: run claude mcp list.
A frequent cause is that npx cannot get to the npm registry. To test the server, run this command in a terminal:
The server prints one JSON line that contains "serverInfo":{"name":"gravity-index".
The server did not send a publisher API key. Set GRAVITY_PUBLISHER_KEY in the env block of your MCP config, or export it in your shell for the CLI. Then restart the agent.
The CLI needs httpx. Install it with pip install --user httpx.
The /search endpoint calls an LLM to select a service, so a response can take some seconds. The CLI waits up to 30 seconds. If you get timeouts all the time, look at https://index.trygravity.com/health. If the problem continues, contact index@trygravity.ai.