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 atindex@trygravity.ai. - For the MCP server, install Node.js 18 or later.
- For the CLI, install Python 3 and the
httpxpackage.
YOUR_API_KEY with your publisher API key.
MCP server (recommended)
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.
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.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 callsgravity_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
-
Go to your local copy of the Gravity repository.
-
Copy the script to a folder on your
PATH. -
Make sure that
~/.local/binis on yourPATH. Add this line to~/.zshrcor~/.bashrc: -
Install
httpx. The CLI uses it for HTTP calls. -
Set your publisher API key.
Use the CLI
Direct API
To call the Index from your own agent or from any language, use the REST API athttps://index.trygravity.com.
{"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
npx fails with ENOENT or cannot find the package
npx fails with ENOENT or cannot find the package
- Make sure that Node.js 18 or later is on your machine:
node -v. - Install the package globally:
npm install -g @gravity-ai/index-mcp. - Find the binary:
which gravity-index-mcp. - In your MCP config, replace the
npxcommand with the absolute path from step 3.
The MCP tools do not show after a restart
The MCP tools do not show after a restart
Look at the MCP server status or logs:The server prints one JSON line that contains
- 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.
npx cannot get to the npm registry. To test the server, run this command in a terminal:"serverInfo":{"name":"gravity-index".Every tool call fails with 401 platform_api_key required
Every tool call fails with 401 platform_api_key required
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 prints Install httpx
The CLI prints Install httpx
The CLI needs
httpx. Install it with pip install --user httpx.Search is slow or times out
Search is slow or times out
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.