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

# Governance & Permissions

> Configure organization and cluster access modes, allowed tools, and authentication for the Remote StreamNative MCP Server.

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.

<Note>
  Both layers must permit an operation for it to succeed. If either layer denies
  the operation, the request fails.
</Note>

**Examples:**

| Server access mode | User role      | Result                                                      |
| ------------------ | -------------- | ----------------------------------------------------------- |
| Read/write         | Administrator  | Full access: user can read and write                        |
| Read/write         | Read-only role | User can only read because user permissions restrict access |
| Read-only          | Administrator  | User can only read because server mode restricts access     |
| Read-only          | Read-only role | User 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](/agent-engine/sn-remote-mcp/remote-mcp-organization-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

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

## 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](/agent-engine/sn-remote-mcp/remote-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**.

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

## 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](/cloud/security/authentication/service-accounts/use-api-keys/api-keys-overview#api-key-v1-vs-api-key-v2) for automated clients, CI/CD pipelines, and headless agent runtimes that need organization-scoped access.

For setup details, see [Connect & Authenticate](/agent-engine/sn-remote-mcp/remote-mcp-access).

## 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](/agent-engine/sn-remote-mcp/remote-mcp-features).