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

# Use Root and Organization-Level MCP Tools

> Use root and organization Remote MCP sessions to inspect and manage StreamNative Cloud resources.

The Remote StreamNative MCP Server supports root and organization-level sessions in addition to fixed cluster sessions. Use a root or organization-level session when you want an MCP client to discover MCP-enabled clusters, switch cluster context during a session, or manage StreamNative Cloud control-plane resources.

## Choose a root or organization endpoint

Use one of the following endpoints:

| Mode         | Endpoint                                              | Use case                                                                                                                                                                                                                           |
| ------------ | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Root         | `https://mcp.streamnative.cloud/mcp`                  | Connect without putting the organization in the URL. The server resolves the organization from the AuthV2 audience in your token. For interactive OAuth flows, provide `X-Organization` or select the organization during sign-in. |
| Organization | `https://mcp.streamnative.cloud/mcp/x/<organization>` | Bind the session to one organization in the URL. Use this when your client or automation can store one endpoint per organization.                                                                                                  |

After connection, the session starts with StreamNative Cloud organization tools. The global identity tool `sncloud_context_whoami` is available for the session. Other organization tools are controlled by the organization feature set. Cluster-specific Pulsar, Kafka, and log tools become available only after you select a cluster with `sncloud_context_use_cluster`.

<Note>
  For a fixed cluster session, use `https://mcp.streamnative.cloud/mcp/x/<organization>/<instance>/<cluster>`. See [Remote MCP Access](/agent-engine/sn-remote-mcp/remote-mcp-access).
</Note>

## Discover and select clusters

Organization-level sessions expose context tools for finding and selecting MCP-enabled clusters.

| Tool                                 | Description                                                                                                                                             |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sncloud_context_whoami`             | Show the authenticated StreamNative Cloud identity and current organization context. This tool is global and is not controlled by `sncloud_context`.    |
| `sncloud_context_available_clusters` | List MCP-enabled Pulsar and Kafka clusters in the current organization, including instance name, cluster name, cluster type, access mode, and endpoint. |
| `sncloud_context_use_cluster`        | Select a Pulsar or Kafka cluster for the current MCP session. Parameters: `instanceName` and `clusterName`.                                             |
| `sncloud_context_reset`              | Clear the selected cluster and return to organization-only context.                                                                                     |

When you select a cluster, the current MCP session becomes a hybrid session. It keeps organization-level tools and adds static Pulsar or Kafka tools for the selected cluster. The selected cluster overlay also adds `sncloud_logs` for logs from Functions, Sources, Sinks, and Kafka Connect connectors in the selected cluster. Dynamic tools such as `functions-as-tools` and `agents-as-tools` are available on fixed cluster endpoints, but not after in-session cluster switching.

## Use StreamNative Cloud prompts

Organization-level sessions also expose StreamNative Cloud prompts that help clients discover and inspect enabled clusters.

| Prompt                  | Description                                                                                                  |
| ----------------------- | ------------------------------------------------------------------------------------------------------------ |
| `list-sncloud-clusters` | Lists MCP-enabled clusters in the current organization, including the cluster type and endpoint metadata.    |
| `read-sncloud-cluster`  | Reads one cluster resource. Parameters: `name` and `type`. `type` must be `PulsarCluster` or `KafkaCluster`. |

Use the `clusterType` returned by `list-sncloud-clusters` when you call `read-sncloud-cluster`. Disabled or non-exposed clusters aren't returned.

## Manage StreamNative Cloud resources

Organization-level sessions expose domain-scoped tools for StreamNative Cloud resources.

| Feature            | Tools                                             | Resources                                                                                                |
| ------------------ | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `sncloud_byoc`     | `sncloud_byoc_read`, `sncloud_byoc_write`         | `CloudConnection`, `CloudEnvironment`, `Volume`, `PoolMember`                                            |
| `sncloud_identity` | `sncloud_identity_read`, `sncloud_identity_write` | `User`, `ServiceAccount`, `ServiceAccountBinding`, `Role`, `RoleBinding`, `OIDCProvider`, `IdentityPool` |
| `sncloud_clusters` | `sncloud_clusters_read`, `sncloud_clusters_write` | `Instance`, `PulsarInstance`, `PulsarCluster`, `PulsarGateway`, `KafkaCluster`                           |

Read tools support `list` and `get` operations. Write tools support `apply` and `delete` operations. `get` and `delete` require `name`. `apply` requires `manifest`, a JSON string that contains one StreamNative Cloud resource.

After `sncloud_context_use_cluster` selects a cluster, the session also exposes `sncloud_logs` for Functions, Sources, Sinks, and Kafka Connect connectors in the selected cluster.

All domain tool families can use these schema helpers:

| Tool                       | Description                                                                                                                                                                                                                                                                                                                                                         |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sncloud_resource_catalog` | List supported resource kinds for a domain: `byoc`, `clusters`, or `identity`.                                                                                                                                                                                                                                                                                      |
| `sncloud_resource_schema`  | Return schema guidance for one resource kind. The default `summary` format is optimized for authoring manifests; `example` returns an example manifest; `jsonschema` returns runtime Kubernetes schema when available; `all` returns summary plus runtime metadata. Use `paths` such as `spec.broker` or `spec.clusterRefs` to keep runtime schema responses small. |

<Warning>
  Write operations can change organization-level resources. Use `dry_run=true`
  before applying changes, and keep the Remote MCP access mode set to
  **Read-Only** unless mutation tools are required.
</Warning>

## Use the recommended mutation workflow

When you create or update a StreamNative Cloud resource through MCP, use this workflow:

1. Call `sncloud_resource_catalog` for the resource domain, such as `clusters` or `identity`.
2. Call `sncloud_resource_schema` for the resource type, such as `PulsarCluster`, `KafkaCluster`, or `ServiceAccount`.
3. Call the matching read tool to inspect existing resources.
4. Compose the resource manifest as a JSON string.
5. Call the matching write tool with `operation=apply` and `dry_run=true`.
6. Review the validation result.
7. Repeat the apply operation with `dry_run=false` only when the dry-run result is acceptable.

The `manifest` argument must be a JSON string. Do not pass YAML or a structured object. Omit `status`, `metadata.managedFields`, and other read-only fields copied from read responses. The schema summary is guidance, not a replacement for server-side validation. Runtime OpenAPI schemas do not encode every cross-field or cross-resource constraint.

## Control organization tools with features

Use `X-MCP-Features` to narrow the organization tool catalog by tool group. For example, `X-MCP-Features: sncloud_context,sncloud_clusters` exposes context tools plus cluster-domain resources. A feature ID can enable multiple MCP tools, including read/write pairs such as `sncloud_clusters_read` and `sncloud_clusters_write`. If an administrator configured allowed tools for the organization MCP entry, the header can only request a subset of that allow list. If you omit `X-MCP-Features`, the server uses the configured organization feature set.

| Feature ID                               | Enables                                                                                                                                       |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `streamnative-cloud` or `cloud`          | All StreamNative Cloud organization tool families.                                                                                            |
| `sncloud_context` or `sncloud-context`   | Cluster discovery and context switch tools: `sncloud_context_available_clusters`, `sncloud_context_use_cluster`, and `sncloud_context_reset`. |
| `sncloud_byoc` or `sncloud-byoc`         | BYOC control-plane tools.                                                                                                                     |
| `sncloud_identity` or `sncloud-identity` | Identity and RBAC resource tools.                                                                                                             |
| `sncloud_clusters` or `sncloud-clusters` | Instance and cluster resource tools.                                                                                                          |

For the full header reference, see [Remote MCP Headers and Feature Selection](/agent-engine/sn-remote-mcp/remote-mcp-features).

## 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. The organization settings control root and organization endpoints. Cluster settings control fixed cluster endpoints and cluster tools added after `sncloud_context_use_cluster` selects a cluster.

## Related StreamNative Cloud documentation

* [Use API Keys to Authenticate to StreamNative Cloud](/cloud/security/authentication/service-accounts/use-api-keys/api-keys-overview) for API Key v2 and organization-scoped service account credentials.
* [Authentication overview](/cloud/security/authentication/authentication-overview) for StreamNative Cloud authentication concepts, including AuthV2 behavior.
* [RBAC overview](/cloud/security/access/rbac/rbac-overview) and [predefined roles](/cloud/security/access/rbac/manage-rbac-roles) for permissions applied to users and service accounts.
* [StreamNative Cloud objects](/cloud/references/cloud-object) for Kubernetes-style resource manifests.
* [Manage StreamNative clusters](/cloud/clusters/manage-clusters/cluster), [cluster configuration](/cloud/clusters/configure-clusters/cluster-configuration-overview), and [Kafka Cluster Guide](/kafka/kafka-cluster-guide) for cluster concepts and service URLs.
* [PulsarCluster API reference](/api-references/cloudapi/pulsarcluster/cloudstreamnativeio_v1alpha1/get-apiscloudstreamnativeiov1alpha1namespaces-pulsarclusters), [PulsarInstance API reference](/api-references/cloudapi/pulsarinstance/cloudstreamnativeio_v1alpha1/get-apiscloudstreamnativeiov1alpha1namespaces-pulsarinstances), and [PulsarGateway API reference](/api-references/cloudapi/pulsargateway/cloudstreamnativeio_v1alpha1/get-apiscloudstreamnativeiov1alpha1namespaces-pulsargateways) for cluster-domain resources. For `KafkaCluster`, use [Kafka Cluster Guide](/kafka/kafka-cluster-guide) for user-facing concepts and `sncloud_resource_schema` for the live manifest schema when available.
* [ServiceAccount API reference](/api-references/cloudapi/serviceaccount/cloudstreamnativeio_v1alpha1/get-apiscloudstreamnativeiov1alpha1namespaces-serviceaccounts) and [API key API reference](/api-references/cloudapi/apikey/cloudstreamnativeio_v1alpha1/get-apiscloudstreamnativeiov1alpha1namespaces-apikeys) for identity-domain resources.