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:

Migrating from the locally installed version

If you previously installed the PubNub MCP Server as a local package (npx @pubnub/mcp@latest), that version is now deprecated. It will continue to work for existing installations, but will not receive new features or updates.

To switch to the hosted server (https://mcp.pubnub.com), remove the old configuration from your AI client first, then follow the setup steps below.

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"
      }
    }
  }
}

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.

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
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.

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.

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

Authentication failures​

If you see authentication errors:

  • Ensure your account is active on the Admin Portal
  • Try revoking and reauthorizing the MCP connection from MCP Connections
  • Check that your OAuth connection hasn't expired

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:

  • Check your network connection
  • Ensure https://mcp.pubnub.com is accessible from your environment (not blocked by a firewall or proxy)

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