--- source_url: https://www.pubnub.com/docs/ai-development/set-up-mcp-server title: Set up the MCP server updated_at: 2026-09-30T07:20:08.000Z --- # Set up the MCP server ## Documentation index To discover more PubNub resources: 1. Fetch [PubNub's llms.txt](https://www.pubnub.com/llms-full.txt) for a list of available pages in Markdown format. 2. Identify relevant URLs from that index. 3. Fetch the target pages. Do not assume a path exists, always check the index first. 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](https://www.pubnub.com/docs/analytics/usage-dashboards/overview.md) analytics. * Publish and subscribe, read message history, and query [Presence](https://www.pubnub.com/docs/presence/overview.md) and [App Context](https://www.pubnub.com/docs/data-storage/metadata/overview.md) data. * Manage [Functions](https://www.pubnub.com/docs/message-processing/serverless/overview.md) and [Illuminate](https://www.pubnub.com/docs/analytics/decisions/overview.md) 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](#local-server-configuration) instead. For how the two differ, see [MCP server](https://www.pubnub.com/docs/ai-development/mcp-server.md). For what each tool does, see [Available MCP tools](https://www.pubnub.com/docs/ai-development/available-mcp-tools.md). ## Before you start Confirm you have: * A [PubNub account](https://admin.pubnub.com/signup). * One of the supported AI tools: [VS Code](https://code.visualstudio.com/), [Cursor](https://www.cursor.com/), [Claude Code](https://www.anthropic.com/claude-code), [Claude Desktop](https://claude.ai/download), [Codex](https://developers.openai.com/codex), [Codex Desktop](https://openai.com/codex-desktop), [Gemini CLI](https://geminicli.com/), [OpenCode](https://opencode.ai/), or another MCP-compatible tool. * MCP connections allowed for your organization. An Account Owner or Account Admin controls this in [organization settings](https://www.pubnub.com/docs/ai-development/manage-mcp-connections.md#control-mcp-access-for-an-organization). 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](https://vscode.dev/redirect/mcp/install?name=pubnub&config=%7B%22url%22%3A%22https%3A%2F%2Fmcp.pubnub.com%22%7D), 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: ```json { "servers": { "PubNub": { "type": "http", "url": "https://mcp.pubnub.com" } } } ``` 2. Sign in when prompted. [Learn more in VS Code documentation](https://code.visualstudio.com/docs/copilot/customization/mcp-servers). ### Cursor 1. Open the [Cursor install link](https://cursor.com/install-mcp?name=PubNub&config=eyJ0eXBlIjoiaHR0cCIsInVybCI6Imh0dHBzOi8vbWNwLnB1Ym51Yi5jb20ifQ%3D%3D), 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: ```json { "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](https://docs.cursor.com/context/model-context-protocol). ### Claude Code 1. In a terminal, run: ```bash 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](https://docs.anthropic.com/en/docs/claude-code/mcp). ### 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](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp). ### Codex 1. In a terminal, run: ```bash codex mcp add pubnub --url https://mcp.pubnub.com ``` 2. Run `codex mcp login pubnub` and sign in. [Learn more in Codex documentation](https://platform.openai.com/docs/guides/tools/model-context-protocol). ### 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](https://help.openai.com/en/articles/11487775). ### Gemini CLI 1. In a terminal, run: ```bash 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](https://github.com/google-gemini/gemini-cli). ### OpenCode 1. Add the following to `opencode.json` in your project root, or to `~/.config/opencode/opencode.json` for all projects: ```json { "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](https://opencode.ai/docs/mcp-servers/). ### 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](https://nodejs.org/en) version 20.0.0 or higher (`node --version` to check). Claude Desktop runs the server through Docker instead, so it needs [Docker](https://www.docker.com/). * A PubNub [API key](https://www.pubnub.com/docs/admin-api.md) 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. :::tip 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](https://admin.pubnub.com). 2. Navigate to **Organization settings** → **API Management**. 3. Find the Service Integration (or [create a new one](https://www.pubnub.com/docs/admin-api.md)) 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 `` 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: ```json { "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}" } } } } ``` #### 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: ```json { "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: ```bash claude mcp add \ --env 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: ```json { "mcpServers": { "PubNub": { "command": "docker", "args": ["run", "-i", "--rm", "-e", "PUBNUB_API_KEY", "pubnub/pubnub-mcp-server"], "env": { "PUBNUB_API_KEY": "" } } } } ``` 3. Restart Claude Desktop and confirm `PubNub` is listed under available tools. #### Codex 1. In a terminal, run: ```bash codex mcp add PubNub \ --env 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](https://geminicli.com/docs/cli/settings/), `~/.gemini/settings.json`, and add the following. Avoid the project-level file, because it lives in your repository: ```json "mcpServers": { "pubnub": { "command": "npx", "args": ["-y", "@pubnub/mcp@latest"], "env": { "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: ```json { "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](https://www.pubnub.com/docs/ai-development/manage-mcp-connections.md#control-mcp-access-for-an-organization). ## Next steps * [Available MCP tools](https://www.pubnub.com/docs/ai-development/available-mcp-tools.md). What each tool does and what access it needs. * [Prompt templates](https://www.pubnub.com/docs/ai-development/prompt-templates.md). Starting prompts for common PubNub build tasks. * [Manage MCP connections](https://www.pubnub.com/docs/ai-development/manage-mcp-connections.md). Revoke hosted connections or turn them off for an organization. * [MCP server](https://www.pubnub.com/docs/ai-development/mcp-server.md). How the hosted and local servers differ and what they can access. Last updated at: 2026-09-30T07:20:08.000Z