Set up the MCP server

Connect an AI coding tool to the PubNub Model Context Protocol (MCP) server so it can work on your PubNub account from plain-language requests. Once connected, the tool can:

• Create and configure apps and keysets.
• Look up current SDK and Chat SDK documentation, and SDK migration guides.
• Read usage metrics and Insights analytics.
• Publish and subscribe, read message history, and query Presence and App Context data.
• Manage Functions and Illuminate resources.

Use the hosted server at https://mcp.pubnub.com if your tool supports remote MCP servers. You sign in with your PubNub account and there's nothing to install. If your tool only runs local servers, run the server locally instead. For how the two differ, see MCP server. For what each tool does, see Available MCP tools.

Before you start

Confirm you have:

• A PubNub account.
• One of the supported AI tools: VS Code, Cursor, Claude Code, Claude Desktop, Codex, Codex Desktop, Gemini CLI, OpenCode, or another MCP-compatible tool.
• MCP connections allowed for your organization. An Account Owner or Account Admin controls this in organization settings. If it's turned off, your organization doesn't appear when you sign in.

Connect to the hosted server

Select your tool. Each flow ends with a PubNub sign-in page. Select the organization to authorize and click Allow access. The connection gets the same permissions your user has in that organization.

If you previously used the local server, remove its entry from your tool's configuration first.

VS Code

1. Open the VS Code install link, select Open in Visual Studio Code, then click Install.

   To add the server by hand instead, add it to .vscode/mcp.json in your project, or to your user configuration with the MCP: Open User Configuration command:

   {
     "servers": {
       "PubNub": {
         "type": "http",
         "url": "https://mcp.pubnub.com"
       }
     }
   }

2. Sign in when prompted.

Learn more in VS Code documentation.

Cursor

1. Open the Cursor install link, select Open Cursor, then click Install.

   To add the server by hand instead, add it to .cursor/mcp.json in your project, or to ~/.cursor/mcp.json for all projects, then click Enable on the notification Cursor shows:

   {
     "mcpServers": {
       "PubNub": {
         "url": "https://mcp.pubnub.com"
       }
     }
   }

2. Sign in when prompted.

3. Open Cursor Settings → Tools & MCP and confirm PubNub is enabled.

Cursor calls MCP tools in Agent mode. Depending on your Cursor rules, you may need to ask the agent to use the PubNub MCP server.

Learn more in Cursor documentation.

Claude Code

1. In a terminal, run:

   claude mcp add --scope user --transport http pubnub https://mcp.pubnub.com

   --scope user makes the server available in all your projects.

2. Run claude, enter /mcp, select pubnub, then select authenticate and sign in.

Learn more in Claude Code documentation.

Claude Desktop

These steps apply to the Pro and Max plans. On an Enterprise plan, an organization administrator adds remote MCP connectors.

1. In Claude Desktop, go to Customize → Connectors.
2. Click +, then select Add custom connector.
3. Enter https://mcp.pubnub.com as the connector URL.
4. Sign in when prompted.

Learn more in Claude Desktop documentation.

Codex

1. In a terminal, run:

   codex mcp add pubnub --url https://mcp.pubnub.com

2. Run codex mcp login pubnub and sign in.

Learn more in Codex documentation.

Codex Desktop

1. Go to Settings → MCP servers and click + Add server.
2. Select Streamable HTTP as the transport type.
3. Enter https://mcp.pubnub.com as the server URL.
4. Sign in when prompted.

Learn more in Codex Desktop documentation.

Gemini CLI

1. In a terminal, run:

   gemini mcp add pubnub --scope user --transport http https://mcp.pubnub.com

2. Run gemini, then run /mcp auth pubnub and sign in.

Learn more in Gemini CLI documentation.

OpenCode

1. Add the following to opencode.json in your project root, or to ~/.config/opencode/opencode.json for all projects:

   {
     "mcp": {
       "pubnub": {
         "type": "remote",
         "url": "https://mcp.pubnub.com",
         "enabled": true
       }
     }
   }

2. Run opencode mcp auth pubnub and sign in.

3. Run opencode mcp list and confirm pubnub is listed as authenticated.

Learn more in OpenCode documentation.

Other AI tool

1. Add a remote MCP server entry to your tool's MCP configuration, with the URL https://mcp.pubnub.com and the transport type your tool calls http, streamable HTTP, or remote.
2. Save and restart the tool, then sign in when prompted.

Local server configuration

The local server is the @pubnub/mcp npm package. Your AI tool starts it on your machine and it authenticates with a PubNub API key instead of a sign-in. It exposes the same tools as the hosted server.

Before you start with the local server

Confirm you have:

• Node.js version 20.0.0 or higher (node --version to check). Claude Desktop runs the server through Docker instead, so it needs Docker.
• A PubNub API key with read and write access to apps and keysets, and read access to secret keys. Anything the key can do, the AI tool can do, so grant only the permissions you want the AI tool to have.

Store your API key securely

Store the API key in a secure location such as a secrets manager, environment variable, or encrypted configuration file. Never commit API keys to source control.

To get the API key, you need to have or create a service integration.

1. Log in to the Admin Portal.

2. Navigate to Organization settings → API Management.

3. Find the Service Integration (or create a new one) to create an API key for.

4. Click + Generate API Key.

5. In the dialog that appears, choose the expiration date for the API key.

6. Click Generate API Key and copy the generated API key, as you won't be able to view it again.

Local server environment variables

Set these in the env block of the server entry.

Variable	Required	Description
PUBNUB_API_KEY	No, but most tools need it	Service Integration API key. Without it, only the documentation tools and the real-time tools you pass a publish and subscribe key to work. App, keyset, usage, Insights, Illuminate, and Functions tools need it.
MCP_ANALYTICS_DISABLED	No	Set to true to turn off the usage analytics the server reports.

Add the local server to your tool

Your AI tool saves its MCP configuration as a plain-text file, so any API key you type into that file stays on disk. Keep the key out of project files that you commit to version control. Where a tool supports it, the examples below read the key from an environment variable or a prompt instead. Otherwise, add the entry to your user-level configuration and replace <your-pubnub-api-key> with your API key.

VS Code

Add the following to .vscode/mcp.json in your project, or to your user configuration with the MCP: Open User Configuration command. VS Code prompts for the key when the server first starts, and doesn't write it to the file:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "pubnub-api-key",
      "description": "PubNub API key",
      "password": true
    }
  ],
  "servers": {
    "PubNub": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@pubnub/mcp@latest"],
      "env": {
        "PUBNUB_API_KEY": "${input:pubnub-api-key}"
      }
    }
  }
}

show all 20 lines

Cursor

1. Set PUBNUB_API_KEY in the environment Cursor starts from, for example in your shell profile.

2. Add the following to .cursor/mcp.json in your project, or to ~/.cursor/mcp.json for all projects. Cursor replaces ${env:PUBNUB_API_KEY} with the value from your environment:

   {
     "mcpServers": {
       "PubNub": {
         "command": "npx",
         "args": ["-y", "@pubnub/mcp@latest"],
         "env": {
           "PUBNUB_API_KEY": "${env:PUBNUB_API_KEY}"
         }
       }
     }
   }

3. Save the file, then click Enable on the notification Cursor shows.

4. Open Cursor Settings → Tools & MCP and confirm PubNub is enabled.

Claude Code

1. In a terminal, run:

   claude mcp add \
     --env PUBNUB_API_KEY=<your-pubnub-api-key> \
     --scope user \
     --transport stdio \
     PubNub \
     -- npx -y @pubnub/mcp@latest

2. Run claude mcp list and confirm PubNub is listed.

Claude Desktop

1. Open or create the configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add the following:

   {
     "mcpServers": {
       "PubNub": {
         "command": "docker",
         "args": ["run", "-i", "--rm", "-e", "PUBNUB_API_KEY", "pubnub/pubnub-mcp-server"],
         "env": {
           "PUBNUB_API_KEY": "<your-pubnub-api-key>"
         }
       }
     }
   }

3. Restart Claude Desktop and confirm PubNub is listed under available tools.

Codex

1. In a terminal, run:

   codex mcp add PubNub \
     --env PUBNUB_API_KEY=<your-pubnub-api-key> \
     -- npx -y @pubnub/mcp@latest

2. Run codex mcp list and confirm PubNub is listed.

Codex Desktop

1. Open Codex Desktop, click Settings, then MCP Servers.
2. Under Custom servers, click + Add server.
3. Set Command to launch to npx and Arguments to -y and @pubnub/mcp@latest.
4. Under Environment variables, add PUBNUB_API_KEY with your API key.
5. Click Save.

Gemini CLI

1. Open your user-level Gemini CLI settings.json file, ~/.gemini/settings.json, and add the following. Avoid the project-level file, because it lives in your repository:

   "mcpServers": {
     "pubnub": {
       "command": "npx",
       "args": ["-y", "@pubnub/mcp@latest"],
       "env": {
         "PUBNUB_API_KEY": "<your-pubnub-api-key>"
       }
     }
   }

2. Run gemini mcp list and confirm pubnub is listed.

OpenCode

1. Set PUBNUB_API_KEY in the environment OpenCode starts from, for example in your shell profile.

2. Add the following to ~/.config/opencode/opencode.json for all projects, or to opencode.json in your project root. OpenCode replaces {env:PUBNUB_API_KEY} with the value from your environment:

   {
     "mcp": {
       "pubnub": {
         "type": "local",
         "command": ["npx", "-y", "@pubnub/mcp@latest"],
         "environment": {
           "PUBNUB_API_KEY": "{env:PUBNUB_API_KEY}"
         }
       }
     }
   }

3. Run opencode mcp list and confirm pubnub is listed.

Other AI tool

1. Add a local (stdio) MCP server entry to your tool's MCP configuration that runs npx -y @pubnub/mcp@latest with PUBNUB_API_KEY set in its environment.
2. Save and restart the tool.

Verify the connection

Ask your AI tool to use a PubNub tool, for example "List my PubNub keysets" or "Publish a test message to the channel test." A working connection returns real account data or a publish timetoken, not an error about a missing or unavailable tool.

If the tool can't reach the server:

• Check the configuration file for syntax errors, then restart the tool.
• If a hosted connection that used to work stops, it probably expired. Hosted connections expire automatically. Sign in again the same way you set it up.
• If your organization is missing from the sign-in page, ask an Account Owner or Account Admin to allow MCP connections in organization settings.

Next steps

• Available MCP tools. What each tool does and what access it needs.
• Prompt templates. Starting prompts for common PubNub build tasks.
• Manage MCP connections. Revoke hosted connections or turn them off for an organization.
• MCP server. How the hosted and local servers differ and what they can access.