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, and Gemini CLI 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:

Setup​

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

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

  1. Create a PubNub account on the Admin Portal and get your 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. Click your account name in the top-right corner and select My Account.

    3. Navigate to the Service Integrations tab.

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

    5. Click + Generate API Key.

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

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

  2. Click the button below to install the PubNub MCP Server in VS Code:

    Open in VS Code

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

  4. When prompted, enter your PubNub API key. This key authenticates the MCP server with the Admin Portal, enabling it to manage your apps and keysets.

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

icon

Manual configuration

Security and authentication​

The PubNub MCP Server uses your API key to authenticate with the Admin Portal and access PubNub real-time APIs.

Authentication​

We recommend using your PubNub API key, provided through the PUBNUB_API_KEY environment variable.

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
SDK Documentation
Read
Access documentation for all supported SDKs

Privacy considerations​

  • Credentials are passed as environment variables and are never persisted by the MCP server

  • 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

Configuration​

You configure the MCP server through environment variables. The setup process for each AI agent handles this automatically, but you can also configure 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
Use PUBNUB_API_KEY instead.

This parameter was required in the previous version of the MCP server. It still works, but will be deprecated.

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

This parameter was required in the previous version of the MCP server. It still works, but will be deprecated.

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 the 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 the 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 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
The MCP server requires Node.js version 20.0.0 or higher. If using Docker, 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. Verify Node.js is installed (version 20.0.0 or higher required):

    node --version

  2. Check your MCP configuration file for syntax errors

  3. Restart your AI assistant after making configuration changes

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

Authentication failures​

If you see authentication errors:

  • Verify your PubNub email and password are correct
  • Ensure your account is active on the Admin Portal
  • 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 start:

  • Ensure no other process is using the same port (for HTTP mode)
  • Check your network connection
  • Verify that npx can access the npm registry

Platform-specific permissions​

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.
Last updated on
Related Resources
On this page