Connect an AI assistant with MCP
Relevan serves a hosted MCP server. An assistant that supports MCP can search your indexes and send feedback through it. You add a URL to the assistant, and you sign in or give it an API key. You do not install anything.
This guide has a section for Claude, ChatGPT, and Grok. The steps come from the documentation of each vendor, which is linked in each section. The screens of these products change often. If a step does not match, follow the vendor’s documentation.
The two URLs
| URL | Authentication | Use it for |
|---|---|---|
https://api.relevan.dev/v1/mcp | OAuth: you sign in to Relevan in the browser | An assistant that can sign in for you |
https://api.relevan.dev/v1/{orgId}/mcp | An API key of the organization | An agent or an API that sends a header |
The Security page of the console shows the OAuth URL, with a copy button. For the API key URL, use the id or the slug of your organization as {orgId}.
With OAuth, the assistant opens the Relevan console. You sign in, pick the organization, and allow the access. With an API key, send the key in the Authorization header as Bearer <your API key>.
Claude
Claude and Claude Desktop
Claude adds a remote MCP server as a custom connector. The connector also works in Claude Desktop and in the mobile apps, because Claude connects from Anthropic’s cloud. See Get started with custom connectors using remote MCP .
On a Pro or Max plan:
- Go to Customize > Connectors.
- Click + Add, then Add custom connector.
- Enter a name, for example
Relevan. - Enter
https://api.relevan.dev/v1/mcp, and click Continue. - Under OAuth client, keep Use Claude’s published identity (Recommended).
- Finish, then click Connect and sign in to Relevan.
On a Team or Enterprise plan, an owner adds the connector first, in Organization settings > Connectors. Then each member opens Customize > Connectors, finds the connector, and clicks Connect. Each member signs in with their own Relevan account.
A Free plan can add one custom connector.
Claude Code
Add the server, then sign in from a Claude Code session. See Connect to MCP servers .
claude mcp add --transport http relevan https://api.relevan.dev/v1/mcpclaude mcp list then shows ! Needs authentication. Start claude, and run /mcp. Select relevan, and choose Authenticate. Your browser opens the Relevan sign-in.
To use an API key in its place, add the server with a header:
claude mcp add --transport http relevan https://api.relevan.dev/v1/{orgId}/mcp \
--header "Authorization: Bearer $RELEVAN_API_KEY"ChatGPT
ChatGPT adds a remote MCP server as a custom MCP server in Plugins. See Connecting custom MCP servers in ChatGPTÂ .
Full MCP support is on ChatGPT Business and Enterprise/Edu, on ChatGPT web. On Business, only admins and owners can add a server. On Enterprise/Edu, admins can let other members add servers. OpenAI says that Pro users can connect custom MCP servers with read and fetch permissions only.
- Go to Plugins.
- Select the plus button, then Add custom MCP server.
- Enter a name, for example
Relevan. - Under Connection, enter
https://api.relevan.dev/v1/mcp. - Configure OAuth as the authentication, and sign in to Relevan.
- Accept the risk warning, select Create as a plugin, and review the tools.
To use the plugin, start a conversation, type @, and select it. Relevan gives refresh tokens (offline_access), so the connection stays signed in.
Grok
xAI has two ways to connect Grok to a remote MCP server. One is a custom connector on grok.com. The other is the remote MCP tools of the xAI API.
grok.com
See Connectors .
- Go to grok.com/connectors .
- Click New Connector, then select Custom.
- Enter
https://api.relevan.dev/v1/mcp, and complete the authentication that Grok asks for.
xAI’s documentation does not say which authentication methods a custom connector supports. If the Relevan sign-in does not open, use the xAI API with an API key.
On Grok Business and Enterprise, an admin first adds the connector in the xAI cloud console.
The xAI API
The xAI API connects to a remote MCP server for each request. It sends a fixed token in the Authorization header, so use the API key URL. See Remote MCP Tools .
curl https://api.x.ai/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $XAI_API_KEY" \
-d '{
"model": "grok-4.7",
"input": [{ "role": "user", "content": "List my Relevan indexes" }],
"tools": [{
"type": "mcp",
"server_url": "https://api.relevan.dev/v1/{orgId}/mcp",
"server_label": "relevan",
"authorization": "<your Relevan API key>"
}]
}'Any other MCP client
Use the OAuth URL if the client supports the MCP authorization flow. Relevan supports dynamic client registration and Client ID Metadata Documents, with PKCE.
Otherwise use the API key URL. Send the key in the Authorization header as Bearer <your API key>, or in the x-api-key header. A console sign-in does not work with the MCP server. The server uses Streamable HTTP and keeps no session.
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.
Scopes
The type of the API key, or the scope that you allow with OAuth, decides which tools the assistant gets.
| Access | Tools |
|---|---|
| Read | list_indexes, describe_index, search, get_filter_values, get_document, send_search_feedback |
| Write | The read tools, and create_index, create_mapping, upsert_documents, delete_document |
With OAuth, only an owner of the organization can allow write access. A read connection gets the same tools and errors as a read key.
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
queryIdfrom thesearchContextof 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 samequeryIdfails 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.
Disconnect an assistant
Open Security in the console. Under Connected MCP clients, click Disconnect. The assistant loses access at once. To stop an agent that uses an API key, revoke the key.
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
searchcall counts against the search rate limit and the monthly search quota, the same as a REST search.