DOCS
Ask AI

MCP server

The Model Context Protocol (MCP) is an open protocol that lets an AI agent call tools exposed by an external system instead of only generating text about it. PubNub runs an MCP server that exposes real PubNub account operations as callable tools: creating a keyset, publishing a message, querying presence, and more. An AI coding assistant can then act on your actual PubNub account instead of guessing at API shapes from its training data.

Any MCP-compatible client can connect to the PubNub MCP server, including Claude Code, Claude Desktop, Cursor, VS Code, Codex, Gemini CLI, and OpenCode. Once connected, you describe what you want in natural language, and the agent decides which PubNub tools to call to do it. For the full catalog of what those tools can do, refer to Available MCP tools. For connecting a client, refer to Set up the MCP server.

Why a PubNub-specific MCP server​

Without account access, an agent can't check which keysets exist, which features a keyset has enabled, or whether a message it published arrived. PubNub MCP tool calls run against the Admin Portal and PubNub's real-time APIs, so the agent works from the state of your account. That covers apps and keysets, real messages, Presence and App Context data, and Illuminate and Functions resources. The agent also pulls current SDK documentation (PubNub maintains more than 50 SDKs, covering web, server, mobile, game engine, and embedded platforms) instead of relying on training data, which reduces outdated API calls in generated code.

Hosted and locally installed servers​

The PubNub MCP server runs in two shapes, and a client connects to exactly one of them at a time:

  • Hosted, at https://mcp.pubnub.com. PubNub runs and maintains the server. A client connects over HTTP and authenticates with OAuth: you sign in, pick an organization, and authorize the connection. There is nothing to install, and the connection inherits your user permissions for that organization.
  • Local, installed on your own machine (for example with npx @pubnub/mcp@latest, or via Docker for clients that require it). The client launches the server as a subprocess and authenticates it with a PubNub API key you provide as an environment variable.

Choose hosted when your client supports remote MCP servers: it needs no install step, no runtime to keep updated, and connections are centrally revocable from Manage MCP connections. Choose local when your client can't reach a remote server.

Local also suits cases where you want the server's credentials to be an API key you control directly, rather than an OAuth session tied to your user account. Both shapes expose the same set of tools. Only the transport and authentication differ. For the exact setup steps per client, refer to Set up the MCP server.

The AI agent sends MCP tool calls to the PubNub MCP server. The server then acts on your PubNub account, which covers apps, keysets, the real-time network, App Context, Functions, and Illuminate. A hosted server reaches the account through OAuth. A local server reaches it through an API key.

Both deployment shapes can reach every category of tool described in Available MCP tools. That includes documentation lookup, app and keyset management, real-time messaging and App Context, Illuminate analytics and automation, Insights analytics, and Functions management.

How the agent picks a keyset​

Real-time tool calls, such as publishing a message or reading presence, take a publish and subscribe key pair as parameters on every call. The agent gets that pair from your account with the manage_keysets tool, or from you. Name the keyset in your request, such as publish to the lobby channel on my staging keyset, to keep the agent on one project. The same applies to the hosted and the local server.

Security model​

The two deployment shapes authenticate differently, but both are scoped to your existing PubNub account permissions rather than granting anything new:

  • The hosted server authenticates with OAuth. Connections expire automatically, inherit your user permissions for the organization you authorized, and are visible and revocable at any time from Manage MCP connections.
  • The local server authenticates with a PubNub API key you generate as a Service Integration and pass in as PUBNUB_API_KEY. Anything that key can do in the Admin Portal, the agent can also do. Scope the key's permissions before handing it to an AI agent. Your AI tool saves the key in its own MCP configuration file, in plain text unless the tool reads it from an environment variable or a prompt. Keep that file out of version control. Refer to Add the local server to your tool.

Neither PubNub MCP server stores your credentials. The server uses them only while it handles a tool call, and every tool call runs within your account's existing permissions and billing limits. The MCP server is a new interface onto your account, not a new privilege level.

Next steps​

  • Set up the MCP server. Connect a hosted or locally installed server to your AI coding client.
  • Available MCP tools. The full catalog of tools, resources, and prompt templates the server exposes.
  • Manage MCP connections. Review, revoke, or restrict hosted MCP connections for your organization.
  • Skills. Pair the MCP server's live account access with focused implementation guidance for PubNub features.

Was this page useful?

Last updated on