Connect an agent with the MCP server

Relevan serves a hosted MCP server. An agent that supports MCP can search your indexes and send feedback through it. You add a URL and an API key to the agent. You do not install anything.

The URL


https://api.relevan.dev/v1/{orgId}/mcp

Use the id or the slug of your organization as {orgId}. The server uses Streamable HTTP and keeps no session.

The API key

Send an API key of the organization in the Authorization header:


Authorization: Bearer <your API key>

The server also accepts the key in the x-api-key header. A console sign-in does not work with the MCP server.

Scopes

The type of the API key decides which tools the agent gets.

Key	Tools
Read key	`list_indexes`, `describe_index`, `search`, `get_filter_values`, `get_document`, `send_search_feedback`
Write key	The read tools, and `create_index`, `create_mapping`, `upsert_documents`, `delete_document`

A read key cannot list or call the tools that change data. Use a read key for an agent that only searches. A leaked read key cannot change your data.

The MCP server has no tool that deletes an index. Delete an index in the console or with the REST API.

Feedback

After each search, the agent sends one judgment with send_search_feedback:

The agent searches and keeps the queryId from the searchContext of the result.
The agent decides whether the results served the user.
The agent sends exactly one judgment for that queryId. A second judgment for the same queryId fails with 409.

The judgment has a grade for the whole search, optional grades of single results, and a description. In description, the agent writes what the user wanted and why the results did or did not match. The tool tells the agent not to copy personal data that the user did not need to share. Relevan keeps description with the same retention as query text.

Relevan uses the judgments to improve the ranking of your index.

Add the server to an agent

Claude Code:


claude mcp add --transport http relevan https://api.relevan.dev/v1/{orgId}/mcp \
  --header "Authorization: Bearer $RELEVAN_API_KEY"

An MCP client with a JSON configuration file:


{
  "mcpServers": {
    "relevan": {
      "type": "http",
      "url": "https://api.relevan.dev/v1/{orgId}/mcp",
      "headers": { "Authorization": "Bearer <your API key>" }
    }
  }
}

The name of the type field and the layout of the file change between clients. See the documentation of your client.

Limits

Keep each tool call under 8 KB of JSON. A larger request gets 413. To load many documents, use the bulk REST endpoint.
A search call counts against the search rate limit and the monthly search quota, the same as a REST search.