Install REVOR AI MCP with an AI assistant

This is the canonical installation guide for AI assistants, automated installers, and users. REVOR AI MCP uses API key authentication by default. Browser OAuth is a compatibility option only when the client cannot securely store a custom header.

Required installation information

Use exactly one authentication method unless diagnosing a client. If both an API key and OAuth token are sent, REVOR AI uses the API key.

Ready-to-use JSON configuration

Clients that expose an mcp.json file or JSON editor can merge this server entry into the existing mcpServers object:

JSONCopy
{
  "mcpServers": {
    "revor-ai": {
      "url": "https://revor.ai/api/mcp",
      "headers": {
        "x-api-key": "<enter the REVOR AI API key privately on this device>"
      },
      "disabled": false
    }
  }
}

This is a remote Streamable HTTP configuration. It requires no command, args, npx, proxy package, or local process. An installation agent must follow these rules:

1. Read the existing client configuration first and merge the revor-ai entry without replacing other mcpServers.
2. Prefer the client's Secret input or secret-reference feature. Do not write a plaintext key into JSON when secure storage is available.
3. If the client only supports a private local JSON file, write the placeholder and tell the user the exact local file and field to replace. Never ask the user to send the key in chat.
4. After the user enters the real key locally, never echo the complete configuration, create a screenshot containing the key, or copy it into chat, logs, or source control.
5. Do not invent environment-variable syntax such as ${REVOR_API_KEY} unless the client's official format explicitly supports it.
6. Save or enable the entry, reload the tool list, and restart the client only if needed. Do not report success until revor_whoami succeeds.

Some clients use a different top-level field or a separate Secret UI. Preserve the same URL and x-api-key header while following that client's native configuration format instead of forcing incompatible JSON.

Instructions for an AI installation assistant

Send this entire block to an AI assistant that can manage MCP settings:

TextCopy
Install REVOR AI MCP and follow these requirements exactly:

1. Use the client's built-in Add remote MCP, Connector, or equivalent feature.
2. Set the name to REVOR AI and the server URL to https://revor.ai/api/mcp.
3. This is a remote MCP service. Do not download an npm package or run npx, pnpm, Docker, or a local server.
4. Use API key authentication by default. If the user has no key, direct them to https://revor.ai/my-api-keys. Configure the key as x-api-key; Authorization: Bearer sk-revor-... is also accepted when the client only supports an Authorization header.
5. If the client lets the assistant open or generate a private Secret input, present that input and ask the user to enter the key there. Never ask for or accept an API key in chat. If private secret storage is unavailable, use browser OAuth instead.
6. For an mcp.json client, merge the revor-ai entry into the existing mcpServers object without replacing other services. Use the JSON structure on this page instead of searching for an npm package or guessing a launch command.
7. If the key cannot be entered securely, write only the placeholder and tell the user which local field to fill. Never request the key in chat or echo a configuration after a real key has been inserted.
8. If secure custom headers are unavailable, use the server-provided browser OAuth flow. Ask the user only to sign in on revor.ai and select Allow access.
9. If both API key and OAuth are configured, the API key takes precedence. Do not keep two credentials unless the user explicitly wants that behavior.
10. Save and enable the connection, reload tools, and call revor_whoami. Report installation as complete only after that call succeeds and the REVOR AI tools are visible.

Option A: API key authentication (preferred)

1. Create or select a REVOR AI API key on the API Keys page.
2. Open the client's secure custom-header or secret configuration.
3. Add the remote server URL https://revor.ai/api/mcp.
4. Add one of these headers:

TextCopy
x-api-key: sk-revor-...

Preferred; or, when the client only accepts an Authorization header:

TextCopy
Authorization: Bearer sk-revor-...

1. Save, connect, reload tools, and call revor_whoami.

For assisted installation, use a private Secret input when the client can present one. Never request or accept the key in chat. If the client cannot securely store the header, use browser OAuth. Do not put the key in documentation, screenshots, source control, logs, or shared configuration.

Option B: Browser OAuth (compatibility only)

1. Add a remote MCP service using the name and server URL only.
2. Ask the client to connect. The unauthenticated response provides OAuth discovery information.
3. Open the browser authorization initiated by the client; do not construct an authorization URL manually.
4. Sign in to revor.ai, verify the client, and select Allow access.
5. Return to the client, reload tools, and call revor_whoami.

The MCP client obtains, stores, and refreshes OAuth tokens automatically. Users must not copy access tokens, refresh tokens, or authorization codes from the browser.

Configuration decision rules

• If secure custom headers are supported, prefer x-api-key.
• If only a secure Authorization header is supported, use Bearer sk-revor-....
• If custom headers are unavailable but browser authorization is supported, use OAuth.
• If both are configured, the API key is authoritative; an invalid API key is not silently replaced by OAuth.
• If the client accepts only command, args, or stdio, that client version cannot connect directly to REVOR AI Remote MCP.
• If a configuration file is required, follow that client's own format and reference the key through its supported secret/environment mechanism when possible.

Do not use a REST API URL, OAuth endpoint, tool name, or callback URL as the MCP server URL.

Installation success criteria

Installation is complete only when:

1. The client reports that REVOR AI is connected.
2. The tool list includes revor_whoami and the research, contact, and customs trade tools.
3. revor_whoami succeeds and confirms the account and the granted granular MCP permissions.
4. A non-billable verification remains available after reconnecting the client.

Use this verification request:

TextCopy
Call revor_whoami to check the current REVOR AI MCP account and permissions, then list the available REVOR AI tools. Do not run a billable query.

Common errors and recovery

The client cannot open an OAuth browser window

Use API key authentication if the client supports secure custom headers. Configure x-api-key and reconnect.

The API key is rejected while OAuth is also configured

API key authentication has priority. Correct or remove the invalid API key; REVOR AI does not silently fall back to OAuth when an API key was explicitly supplied.

The server returns 401 without an API key

The client should follow the WWW-Authenticate discovery information and start OAuth. Alternatively, configure an API key securely.

The server returns permission_denied

The API key does not have permission for that tool, or the account plan does not include the capability. Update the key permissions or use an appropriate key. OAuth does not override an explicitly supplied restricted API key.

An old connection keeps using the wrong authentication

Some clients cache headers and OAuth tokens. Delete and recreate the connection, or explicitly remove the stale credential before reconnecting.

Authorization lifetime

API keys remain usable until they expire or are revoked and can be independently restricted and rate-limited. Rotate a key if it may have been exposed.

OAuth access tokens are valid for 15 minutes and are renewed automatically with rotating refresh tokens. Each refresh token has a 30-day lifetime. Restarting the web service or closing the authorization tab does not revoke access.