On this page

PubNub MCP Server

The PubNub Model Context Protocol (MCP) Server enables AI-powered development environments to build, use, and troubleshoot real-time PubNub apps using natural language.

For example, you can ask your AI coding assistant to build a real-time chat with presence or publish a message to a PubNub channel in plain English.

Who it's for and what it does​

The PubNub MCP Server is designed for anyone who wants to:

  • Build real-time applications using AI-assisted coding tools.
  • Integrate PubNub features into their applications without deep SDK expertise.
  • Manage PubNub apps, keysets, and real-time messaging through natural language.

It works with MCP-compatible AI assistants including Visual Studio Code, Cursor IDE, Claude Code, Claude Desktop, Codex, Codex Desktop, Gemini CLI, and OpenCode by accessing:

  • Admin Portal (read/write) to create and manage apps, configure keysets, and retrieve account information
  • PubNub real-time APIs (read/write) to publish messages, subscribe to channels, manage presence, and handle App Context (user/channel metadata)
  • SDK documentation (read-only) to access comprehensive documentation for 20+ programming languages and the Chat SDKs

For a complete list of available tools, resources, and prompts, refer to Available tools.

Prerequisites​

Before you begin, ensure you have:

For the local server, you also need:

  • Node.js installed (version 20.0.0 or higher)

    node --version

  • A PubNub API key

    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.

Hosted vs. local installation​

The hosted server (https://mcp.pubnub.com) is managed by PubNub and provides the easiest way to get started — no installation required, and authentication is handled automatically via OAuth. If your AI tool doesn't support remote MCP servers, use the locally installed version (npx @pubnub/mcp@latest) instead.

Setup​

To set up the PubNub MCP Server, follow these steps:

To set up the PubNub MCP Server with VS Code, follow these steps:

Add with one click:

  1. Click the button below to install the server in VS Code:

    Open in VS Code

  2. Select Open in Visual Studio Code on the page that appears, then click Install in VS Code.

  3. Select the organization you want to authorize and review the permissions.

  4. Click Allow access to complete the authorization.

  5. Ask the AI agent to build your PubNub-powered app for you by describing the functionality yourself or by using a sample prompt.

or add manually in VS Code:

Add the following to your VS Code settings.json:

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

Learn more in VS Code documentation

Security and authentication​

The PubNub MCP Server uses OAuth to authenticate with the Admin Portal API.

OAuth authentication​

OAuth connections provide a seamless and secure authentication experience:

  • No manual key management - Simply sign in to PubNub and authorize access
  • Automatic expiration - Connections expire automatically for security
  • Revocable access - Revoke connections anytime from MCP Connections
  • Multi-organization support - Select which organization to authorize during the OAuth flow

OAuth connections inherit your user permissions for the selected organization.

Managing connections​

You can view and manage your MCP connections in the Admin Portal:

  • View connections: Go to Profile Settings → MCP Connections to see all active MCP client connections.
  • Revoke access: Click Remove next to any connection to revoke it immediately.
  • Block MCP access: Account administrators can disable MCP access for the entire organization in Account Settings → MCP Connection Access.

API key authentication (local server)​

For the locally installed MCP server, authentication uses your PubNub API key passed as the PUBNUB_API_KEY environment variable. For the full list of required permissions and additional configuration options, refer to Local server configuration.

Data access​

The MCP server can access the following data on your behalf:

CategoryAccess LevelDescription
Apps
Read/Write
List, create, and update PubNub applications
Keysets
Read/Write
List, create, and update keysets with feature configurations
Messages
Read/Write
Publish messages to channels, retrieve message history
Presence
Read
Query channel occupancy and user presence information
App Context
Read/Write
Manage user metadata, channel metadata, and memberships
Illuminate
Read/Write
Manage Business Objects, metrics, queries, Decisions, and Dashboards
Insights
Read
Query aggregated analytics metrics for channels, users, messages, user behavior, and devices. Requires Insights Premium tier and a Service Integration API key with Account-level Insights Read permission.
SDK Documentation
Read
Access documentation for all supported SDKs

Privacy considerations​

  • Credentials are never persisted by the MCP server beyond the session.

  • Real-time operations (publish, subscribe, presence) require publish and subscribe keys from your keysets.

    Account information

    The MCP server retrieves the account information for you. You don't need to provide it yourself.

  • The server operates within your PubNub account's permissions and billing limits.

Local server configuration​

You configure the locally installed MCP server through environment variables. The setup process for each AI agent handles this automatically, but you can also set these manually.

Authentication variables​

The MCP server supports two authentication methods for accessing the Admin Portal API:

VariableDescription
PUBNUB_API_KEY
Your API key. The API key takes precedence over email/password authentication.

Ensure your API key has at least the following permissions:
LevelPubNub resourceAccess
AccountAppRead and write
AccountKeysetRead and write
AccountSecret keyRead
PUBNUB_EMAIL
Deprecated — use PUBNUB_API_KEY instead.

Your PubNub account email address. If both the API key and email/password are provided, the API key takes precedence.
PUBNUB_PASSWORD
Deprecated — use PUBNUB_API_KEY instead.

Your PubNub account password. If both the API key and email/password are provided, the API key takes precedence.

Optional variables​

VariableDefaultDescription
PUBNUB_USER_ID
pubnub-mcp
User ID for PubNub client operations.
PUBNUB_PUBLISH_KEY
n/a
PubNub publish key for real-time operations.

Setting this variable overrides dynamic mode and forces the server to operate in fixed mode. For more information, see PubNub keys configuration.
PUBNUB_SUBSCRIBE_KEY
n/a
PubNub subscribe key for real-time operations.

Setting this variable overrides dynamic mode and forces the server to operate in fixed mode. For more information, see PubNub keys configuration.

PubNub keys configuration​

The MCP server supports two modes for handling PubNub publish/subscribe keys: dynamic (default) and fixed.

Dynamic mode (default)​

When PUBNUB_PUBLISH_KEY and PUBNUB_SUBSCRIBE_KEY aren't set, the server operates in dynamic mode:

  • The AI agent can work with multiple keysets in a single session.
  • Keys can be discovered dynamically via the manage_keysets tool.
  • The agent decides which keyset to use based on context.

This mode is ideal when you want the AI to help manage multiple applications or when the keyset should be determined at runtime.

Fixed mode​

When both PUBNUB_PUBLISH_KEY and PUBNUB_SUBSCRIBE_KEY are set, the server operates in fixed mode:

  • Key parameters are hidden from tool schemas entirely.
  • All real-time operations use the configured keys automatically.
  • Operations are limited to a single keyset.

This mode is ideal for focused workflows where you're working with a specific application.

Example fixed mode configuration​
{
  "env": {
    "PUBNUB_API_KEY": "<your-pubnub-api-key>",
    "PUBNUB_PUBLISH_KEY": "pub-c-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "PUBNUB_SUBSCRIBE_KEY": "sub-c-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

Considerations​

Consider the following when using the PubNub MCP Server:

ConsiderationDetails
Subscription timeout
The subscribe_and_receive_pubnub_messages tool has a maximum timeout of 30 seconds. For longer subscriptions, you need to call the tool multiple times.
Immutable keyset settings
When creating keysets, certain region settings cannot be changed after creation:
  • App Context region (objects_region): The storage region for user and channel metadata
  • Files region (files_s3_bucket_region): The S3 bucket region for file storage
Always confirm region settings with the user before creating a keyset, as you can't modify them later.
Message Persistence retention limits
Message history retention varies by billing tier.
See API limits.
File storage retention limits
File storage retention also varies by billing tier.
See API limits.
Node.js requirement (local server)
The locally installed MCP server requires Node.js version 20.0.0 or higher. If using Docker (Claude Desktop local setup), this requirement is handled automatically.

Troubleshooting​

If you encounter issues with the PubNub MCP Server, follow these troubleshooting steps.

MCP server not appearing in tools list​

If the PubNub MCP server doesn't appear in your AI assistant's tools list:

  1. Check your MCP configuration file for syntax errors.

  2. Restart your AI assistant after making configuration changes.

  3. In Cursor, navigate to Settings -> Tools & MCP and ensure the server is enabled.

  4. For the local server, verify Node.js is installed (version 20.0.0 or higher):

    node --version

Authentication failures​

If you see authentication errors:

  • Ensure your account is active on the Admin Portal.
  • Hosted server: Try revoking and reauthorizing the MCP connection from MCP Connections. Check that your OAuth connection hasn't expired.
  • Local server: Verify your API key is valid and has the required permissions (refer to Authentication variables). Check that environment variables are properly set — no extra spaces or quotes.

Tool invocations failures​

ErrorCause/Solution
Missing keys error
The tool requires publish and subscribe keys. Use manage_keysets with the "list" operation to retrieve them from your account.
Permission denied
Your keyset may not have the required features enabled (for example, Presence or App Context).
Invalid parameters
Check that you're providing all required parameters in the correct format.

Connection problems​

If the MCP server fails to connect:

  • Hosted server: Check your network connection. Ensure https://mcp.pubnub.com is accessible from your environment (not blocked by a firewall or proxy).
  • Local server: Verify that npx can access the npm registry.

Platform-specific permissions (local server)​

PlatformCause/Solution
macOS/Linux
If you encounter permission errors, ensure the npx command has execute permissions.
Windows
Use PowerShell or Command Prompt with administrator privileges if you encounter installation issues.

Sample prompts​

Happy vibe coding!

  • Write an app that lets the user watch streaming videos with built-in multi-user chat with PubNub.
  • Create a new PubNub keyset for me.
  • Write a PubNub app for on-demand delivery of groceries with a map.
  • Write a PubNub app that tracks the location of a package in real-time.
  • Write a PubNub app that shows the weather forecast in real-time.
  • Write a PubNub app that lets users play multiplayer games with friends.
  • Write a PubNub app that shows live stock prices and news updates.
  • Write a PubNub app that lets users create and share playlists with friends.
  • Build a PubNub JavaScript app that subscribes to the my_channel channel and logs messages to the console.
  • Publish a message to the my_channel channel with the message Hello, PubNub!.
  • Show me the PubNub JavaScript SDK documentation for subscribe().
  • List all available PubNub Functions.
  • Fetch the Python SDK docs for the publish() method.
  • Fetch the message history for the test channel.
  • Retrieve presence information (occupancy and UUIDs) for the test channel and the default channel group.
  • Show me an Insights snapshot for my PubNub account for the last 7 days.
  • What are my top 20 channels by message volume today?
  • Show me new vs. recurring user trends for the last 30 days.
  • What devices are my subscribers using this week?
Last updated on
Related Resources
On this page