Connecting your AI

This page explains, for each AI, where to paste your server's URL or key. The blocks below are the same as in the server's "Connection" tab.

Before you connect

• The server must be "active": when it is "draft" or "disabled", the AI receives a 403 error (see Servers and MCP key).
• On a server whose target API uses OAuth 2.0, there is no key: see Servers using OAuth.
• The MCP key is a secret shown only once, when the server is created or the key is regenerated. If you lost it, regenerate it.
• In the "Connection" tab, choose your AI: the real URL and key are already filled in right after creation or regeneration. Otherwise the blocks show <YOUR_KEY>: replace it with your key.
• There are two URL forms (see the URLs): the URL with the key in the Authorization header (Claude Code, Cursor, VS Code) and the URL that contains the key (claude.ai, Claude Desktop, ChatGPT). The latter is a secret: do not share it.

claude.ai

Add a custom connector with the URL that contains your key: server name, URL, no authentication. On a Team or Enterprise plan, an Owner adds it from the organization settings.

Customize > Connectors > Add custom connector
Name: my-server
Remote MCP server URL: https://mcp.example.com/k/<your-key>/mcp
Authentication: No sign-in

Claude Desktop

Remote servers are added as connectors of your Claude account, on the same screen as claude.ai. The connector is shared with your claude.ai account.

Customize > Connectors > Add custom connector
Name: my-server
Remote MCP server URL: https://mcp.example.com/k/<your-key>/mcp
Authentication: No sign-in

Claude Code

Run the command in your terminal: it uses the URL with the Authorization header. To share the configuration with a team, use the project's .mcp.json file instead: the key stays in the VOOZEO_KEY environment variable and is not written in the file.

claude mcp add --transport http my-server https://mcp.example.com/s/<server-id>/mcp --header "Authorization: Bearer <your-key>"

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "https://mcp.example.com/s/<server-id>/mcp",
      "headers": {
        "Authorization": "Bearer ${VOOZEO_KEY}"
      }
    }
  }
}

ChatGPT

Add a custom MCP server with the URL that contains your key, with no authentication. Menu names and developer mode depend on your ChatGPT plan.

Plugins > + > Add custom MCP server
Name: my-server
Server URL: https://mcp.example.com/k/<your-key>/mcp
Authentication: No authentication

Cursor

Click "Add to Cursor" in the "Add in one click" card of the "Connection" tab: Cursor opens and asks you to confirm before it adds the server. The button appears only while your key is displayed (right after creating the server or regenerating the key), or for a server that uses OAuth, and it is hidden in the Android app. The link contains your key: use it only on your own computer. Otherwise, edit the file by hand:

Paste the block into ~/.cursor/mcp.json (global) or .cursor/mcp.json (project). The variant reads the key from the VOOZEO_KEY environment variable so it is not written in the file.

{
  "mcpServers": {
    "my-server": {
      "url": "https://mcp.example.com/s/<server-id>/mcp",
      "headers": {
        "Authorization": "Bearer <your-key>"
      }
    }
  }
}

{
  "mcpServers": {
    "my-server": {
      "url": "https://mcp.example.com/s/<server-id>/mcp",
      "headers": {
        "Authorization": "Bearer ${env:VOOZEO_KEY}"
      }
    }
  }
}

VS Code

"Add to VS Code" works the same way: VS Code opens and asks you to confirm. The link contains your key, so VS Code does not prompt for it. To keep the key out of the file, use the block below instead.

Paste the block into .vscode/mcp.json. VS Code asks for the key on first start and does not store it in the file.

{
  "inputs": [
    {
      "type": "promptString",
      "id": "voozeo-key",
      "description": "Voozeo API key",
      "password": true
    }
  ],
  "servers": {
    "my-server": {
      "type": "http",
      "url": "https://mcp.example.com/s/<server-id>/mcp",
      "headers": {
        "Authorization": "Bearer ${input:voozeo-key}"
      }
    }
  }
}

Servers using OAuth

When the target API of your server uses OAuth 2.0, there is no MCP key: the "Connection" tab shows an "OAuth" block with the server URL alone, https://mcp.example.com/s/<server-id>/mcp (the real one is in the tab), and no "Regenerate key" button.

1. Add the server to your AI with this URL, without any header or key (syntax below).
2. On the first call, the AI opens your browser on a Voozeo consent page: it shows the address that will receive the access (check it), the name the application declares (not verified), the provider where you will sign in and the scopes requested. Click "Allow", or "Deny".
3. You then sign in at the API provider with your own account and accept. The AI is connected: each tool call goes out with your provider token, which the AI never sees.

Each person who uses the server signs in with their own account. The AI keeps the connection active as long as it is used at least once every 30 days.

Syntax per AI (replace the URL with the one in the tab):

• claude.ai: Customize > Connectors > Add custom connector, then:

Name: my-server
Remote MCP server URL: https://mcp.example.com/s/<server-id>/mcp
Authentication: Sign in now
OAuth client: Use Claude's published identity
Add, then Connect

• Claude Desktop: same connectors as claude.ai (Customize > Connectors > Add custom connector, the URL, then Connect).
• Claude Code: run the command, then type /mcp in Claude Code to sign in.

claude mcp add --transport http my-server https://mcp.example.com/s/<server-id>/mcp

• ChatGPT: Plugins > + > Add custom MCP server, the URL, authentication "OAuth", then "Create as a plugin" and connect.
• Cursor (~/.cursor/mcp.json or .cursor/mcp.json):

{ "mcpServers": { "my-server": { "url": "https://mcp.example.com/s/<server-id>/mcp" } } }

• VS Code (.vscode/mcp.json):

{ "servers": { "my-server": { "type": "http", "url": "https://mcp.example.com/s/<server-id>/mcp" } } }

AIs that run only in a web browser (with no server side and no desktop app) cannot connect with OAuth. If the AI asks you to sign in again, see Sign-in required.

Per-user credentials

When the target API of your server uses the "Forwarded by caller" type, the "Connection" tab shows an "OAuth gateway" block with the URL that contains the key, to declare in a gateway placed in front of Voozeo. Do not give this URL to users. With the Authorization header, the blocks that use the key in a header are hidden. See Per-user credentials with an OAuth gateway.

Check the connection

1. Ask your AI to list this server's tools, or ask a question that needs one.
2. Open the "Log" tab: every tool call appears there (see Call log).
3. If in doubt, try the tool first in the sandbox.

Example: after adding the "Catalog" server to Claude Code, you write "Find product 42". The AI calls the get_product tool, and a "Success" line appears in the log.

Troubleshooting

• The AI reports an authentication error (401): the key is missing, wrong, from another server, or was regenerated. See 401. On an OAuth server, the AI must sign in again: see Sign-in required.
• The AI reports access denied (403): the server is not "active" or the workspace is suspended. See 403.
• Calls fail with a quota message: see quota reached.
• For the menus specific to each AI, see its official documentation, linked in the "Connection" tab ("Official documentation").