Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.streamnative.io/llms.txt

Use this file to discover all available pages before exploring further.

The Remote StreamNative MCP Server provides two layers of access control: server access mode and user permissions. Together, these layers determine what operations an MCP client can perform on StreamNative Cloud organization resources or a selected cluster.

​
How access control works

When an MCP client sends a request, the server evaluates three things:
  1. MCP availability: whether MCP is enabled for the organization and whether the target cluster is enabled for MCP.
  2. Server access mode: the maximum level of operations the MCP server allows on the organization entry or cluster entry (read-only or read/write). This is configured by an administrator in the Console.
  3. User permissions: the StreamNative Cloud roles assigned to the authenticated user or service account. These roles determine which resources the user can access.
The server access mode sets the ceiling. User permissions further restrict what is allowed within that ceiling.
Both layers must permit an operation for it to succeed. If either layer denies the operation, the request fails.
Examples:
Server access modeUser roleResult
Read/writeAdministratorFull access: user can read and write
Read/writeRead-only roleUser can only read because user permissions restrict access
Read-onlyAdministratorUser can only read because server mode restricts access
Read-onlyRead-only roleUser can only read

​
Enable MCP for your organization

Before you can configure MCP on individual clusters, enable the feature for your organization.
  1. In the StreamNative Cloud Console, navigate to Settings > Preview Features.
  2. Enable MCP Server.
  3. After you enable the feature, the Settings > MCP page displays a table of all clusters in your organization with their MCP status.
Organization-level endpoints, including https://mcp.streamnative.cloud/mcp and https://mcp.streamnative.cloud/mcp/x/<organization>, require organization-level MCP access and AuthV2 organization authentication. Fixed cluster endpoints also require organization-level MCP access. Use root and organization endpoints for StreamNative Cloud organization tools and in-session cluster discovery. See Root and Organization-Level Tools.

​
Configure organization MCP access

Organization MCP settings control root and organization endpoints. They also set the access mode and maximum tool catalog for StreamNative Cloud organization tools. Configure these values from the organization MCP settings when available:
  • Enabled - makes root, organization, and fixed cluster endpoints available for the organization.
  • Access mode - Read-Only blocks organization-level mutation calls. Read/Write allows mutation calls when user permissions also allow them.
  • Allowed tools - sets the maximum organization tool catalog, such as cluster discovery, BYOC resources, identity and RBAC resources, cluster resources, and workspaces.
Manage organization-level MCP access from the StreamNative Cloud Console.

​
Enable MCP per cluster

From the organization-level MCP settings page (Settings > MCP):
  1. Locate the Pulsar or Kafka cluster in the table.
  2. Toggle MCP on for the cluster.
  3. Click Configure to navigate to the cluster-level MCP settings.
You can also disable MCP for a cluster at any time by toggling it off. Disabling MCP disconnects active MCP sessions for that cluster, removes the cluster from organization-level discovery, and prevents new fixed cluster sessions from using the cluster endpoint.

​
Configure access mode

The access mode controls the maximum level of operations the MCP server allows. Configure it from the cluster’s MCP Permissions tab in the Console.

​
Read-Only

The MCP server blocks mutation operations. For some organization-level tool groups, write-capable tools can still appear in the catalog, but apply and delete calls fail while read-only mode is active. Use read-only mode for:
  • View cluster information and health metrics
  • List tenants, namespaces, and topics
  • Peek at messages
  • Retrieve schemas and configuration
  • View subscription and consumer group status

​
Read/Write

The MCP server exposes all read operations plus tools that modify resources:
  • Create and delete topics
  • Produce messages
  • Manage schemas (create, update, delete)
  • Create and manage subscriptions
  • Manage connectors and functions
Set the access mode to Read-Only for clusters where MCP users should not modify resources. This provides a safety net even if a user has broad permissions in StreamNative Cloud.

​
Configure allowed tools

From the cluster’s MCP Permissions tab, you can select which tool groups are available through MCP for this cluster. This provides fine-grained control over what MCP clients can do.
  • Pulsar clusters display Pulsar, StreamNative Cloud, and compatible dynamic tool groups.
  • Kafka clusters display Kafka and StreamNative Cloud tool groups. Kafka Connect can be accepted as a feature ID, but Kafka Connect tools are not exposed on Remote MCP Kafka cluster sessions in the current preview.
The selected tools form an allow list. If a client also sends X-MCP-Features, the request can only narrow the catalog to a subset of this allow list. It cannot enable tools that an administrator disabled in the Console. The available tool groups match the tool IDs documented in the MCP Tools Reference.

​
Manage tool groups

  1. Navigate to the cluster’s MCP settings and open the Permissions tab.
  2. Use the Select All checkbox to enable or disable all tool groups at once, or toggle individual tool groups.
  3. Click Save Changes to apply your selection.
  4. To revert to the default configuration, click Reset to Defaults.
Start with a minimal set of tool groups and add more as needed. Fewer tools reduce token usage and improve tool selection accuracy for AI agents.

​
Authentication and user permissions

The authenticated identity determines which StreamNative Cloud resources the MCP client can access.

​
OAuth 2.1

When a user signs in through OAuth 2.1 (for example, from an IDE), their StreamNative Cloud identity and roles determine access. The MCP server scopes tool discovery and execution to the resources the user is authorized to reach.

​
Service account API keys

When a client authenticates with a service account API key, the service account’s assigned roles determine access. Use API Key v2 for automated clients, CI/CD pipelines, and headless agent runtimes that need organization-scoped access. For setup details, see Connect & Authenticate.

​
Console UI reference

The cluster-level MCP settings page has two tabs:

​
Connection tab

Displays the cluster’s MCP endpoint URL and provides ready-to-use configuration examples for:
  • Claude Code - claude mcp add-json command
  • Cursor - JSON configuration for .cursor/mcp.json
  • VS Code - JSON configuration for .vscode/mcp.json
  • cURL - command-line example for testing the endpoint
The connection examples support OAuth 2.1 and API key authentication. API key examples send Authorization: Bearer <api-key>. Use API Key v2 for organization-scoped automation.

​
Permissions tab

Provides controls for:
  • Access mode - toggle between Read-Only and Read/Write
  • Allowed tools - select which tool groups are available, with Select All, individual toggles, Reset to Defaults, and Save Changes

​
Manage MCP settings in the Console

Use the StreamNative Cloud Console to manage MCP availability, access mode, and allowed tools for your organization and clusters. Client headers can narrow the configured tool catalog but cannot enable tools that an administrator disabled in the Console. For the full header reference, see Remote MCP Headers and Feature Selection.