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

# Remote MCP Headers and Feature Selection

> Configure headers and feature selection when connecting to the Remote StreamNative MCP Server.

The Remote StreamNative MCP Server exposes a wide catalog of tools. Clients can use HTTP headers to authenticate, bind root sessions to an organization, request read-only behavior, and narrow the tool catalog. Administrators can use the StreamNative Cloud Console to enable MCP access and set the maximum tool catalog.

<Note>
  Send these headers to a root, organization, or cluster endpoint. See [Remote
  MCP Access](/agent-engine/sn-remote-mcp/remote-mcp-access) for endpoint
  construction details.
</Note>

## Header reference

| Header           | Description                                                                                                                                                                                                                                                                                                                                                                                         |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Authorization`  | Set to `Bearer <token>` for authenticated MCP requests. The token can be an OAuth 2.1 access token or a service account API key. For non-interactive clients, use an [API Key v2](/cloud/security/authentication/service-accounts/use-api-keys/api-keys-overview#api-key-v1-vs-api-key-v2).                                                                                                         |
| `X-Organization` | Optional organization hint for the root `/mcp` endpoint and root OAuth discovery. Use it when the organization is not present in the URL. The value must be a single organization path segment. If both the token and header provide an organization, they must match. If no header is supplied for an interactive root OAuth flow, the sign-in flow can prompt the user to select an organization. |
| `X-MCP-Readonly` | Requests read-only catalog behavior. Accepted true values are `true`, `1`, and `yes`. If the server access mode is Read-Only, mutations are blocked even when this header is omitted. False or omitted values cannot bypass a Read-Only server access mode.                                                                                                                                         |
| `X-MCP-Features` | Comma-separated list of feature identifiers that narrows the tool catalog by tool group. Values are trimmed and case-insensitive. A feature ID can enable multiple MCP tools, including separate read and write tools for the same resource family. The header also controls MCP resources, such as Pulsar resource paths, when the selected features expose resources.                             |

## How feature selection works

* When `X-MCP-Features` is omitted, the server uses the configured default tool set. Pulsar and organization sessions default broadly; Kafka sessions default to Kafka-compatible tools.
* If an administrator configured an allowed-tools list in the Console, the list acts as an allow list. `X-MCP-Features` can request only a subset of that allow list.
* Unsupported feature IDs cause the request to fail when the endpoint has an explicit allow list. Without an allow list, the server falls back to defaults.
* Kafka cluster sessions normalize broad requests such as `all` to Kafka-compatible features. Pulsar-only features requested on Kafka cluster endpoints are ignored; if none of the requested features apply, the request fails.
* Organization-level sessions use StreamNative Cloud features such as `streamnative-cloud`, `sncloud_context`, `sncloud_clusters`, and `sncloud_identity`. Pulsar or Kafka tools are added only after `sncloud_context_use_cluster` selects a cluster.
* Dynamic `functions-as-tools` and `agents-as-tools` run only on fixed Pulsar cluster endpoints. They are not added after a root or organization session selects a cluster with `sncloud_context_use_cluster`.
* Mixed administration feature groups can expose separate read and write tools. For example, `pulsar-admin-topics` can expose `pulsar_admin_topic_read` and `pulsar_admin_topic_write`, and `kafka-admin` can expose `kafka_admin_topics_read` and `kafka_admin_topics_write`.
* `X-MCP-Readonly: true` requests a read-only catalog from a read/write-enabled endpoint. The server omits write or destructive tools where possible and blocks mutation calls server-side. A server configured in Read-Only access mode is the ceiling and cannot be bypassed by omitting the header or setting it to false.
* Start with a minimal feature list to reduce token usage and improve tool selection accuracy.

## Available feature identifiers

Use these values inside the `X-MCP-Features` header. Separate multiple values with commas.

### Combination feature sets

| Feature ID   | Description                                                                      |
| ------------ | -------------------------------------------------------------------------------- |
| `all`        | Enables every available capability across StreamNative Cloud, Pulsar, and Kafka. |
| `all-pulsar` | Includes Pulsar tooling features.                                                |
| `pulsar`     | Alias for `all-pulsar`.                                                          |
| `all-kafka`  | Includes Kafka tooling features.                                                 |
| `kafka`      | Alias for `all-kafka`.                                                           |

### Kafka tooling

| Feature ID                    | Description                                                                                                                                            |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `kafka-admin`                 | Kafka administration tools, including topics, partitions, and consumer groups.                                                                         |
| `kafka-client`                | Kafka produce and consume tools.                                                                                                                       |
| `kafka-admin-schema-registry` | Schema Registry tools.                                                                                                                                 |
| `kafka-admin-kafka-connect`   | Kafka Connect tools. This feature ID is accepted, but Kafka Connect tools are not exposed on Remote MCP Kafka cluster sessions in the current preview. |

### Pulsar tooling

| Feature ID                         | Alias              | Description                       |
| ---------------------------------- | ------------------ | --------------------------------- |
| `pulsar-admin`                     |                    | Pulsar administration tools.      |
| `pulsar-client`                    |                    | Pulsar produce and consume tools. |
| `pulsar-admin-topics`              | `topics`           | Topic administration.             |
| `pulsar-admin-namespaces`          | `namespaces`       | Namespace administration.         |
| `pulsar-admin-tenants`             | `tenants`          | Tenant administration.            |
| `pulsar-admin-brokers`             | `brokers`          | Broker information.               |
| `pulsar-admin-brokers-status`      | `brokers-status`   | Broker status.                    |
| `pulsar-admin-broker-stats`        | `broker-stats`     | Broker statistics.                |
| `pulsar-admin-clusters`            | `clusters`         | Pulsar cluster metadata.          |
| `pulsar-admin-functions`           | `functions`        | Pulsar Functions administration.  |
| `pulsar-admin-functions-worker`    | `functions-worker` | Functions worker status.          |
| `pulsar-admin-sinks`               | `sinks`            | Pulsar IO sinks.                  |
| `pulsar-admin-sources`             | `sources`          | Pulsar IO sources.                |
| `pulsar-admin-namespace-policy`    | `namespace-policy` | Namespace policies.               |
| `pulsar-admin-ns-isolation-policy` | `ns-isolation`     | Namespace isolation policies.     |
| `pulsar-admin-packages`            | `packages`         | Pulsar packages.                  |
| `pulsar-admin-resource-quotas`     | `resource-quotas`  | Resource quotas.                  |
| `pulsar-admin-schemas`             | `schemas`          | Topic schemas.                    |
| `pulsar-admin-subscriptions`       | `subscriptions`    | Topic subscriptions.              |
| `pulsar-admin-topic-policy`        | `topic-policy`     | Topic-level policies.             |

### StreamNative Cloud tooling

| Feature ID           | Alias              | Description                                                                                                                              |
| -------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `streamnative-cloud` | `cloud`            | All StreamNative Cloud organization tool families.                                                                                       |
| `sncloud_context`    | `sncloud-context`  | Organization context, cluster discovery, and in-session cluster switching.                                                               |
| `sncloud_byoc`       | `sncloud-byoc`     | BYOC resources, including CloudConnection, CloudEnvironment, Volume, and PoolMember.                                                     |
| `sncloud_identity`   | `sncloud-identity` | Identity and RBAC resources, including User, ServiceAccount, ServiceAccountBinding, Role, RoleBinding, `OIDCProvider`, and IdentityPool. |
| `sncloud_clusters`   | `sncloud-clusters` | Instance and cluster resources, including Instance, PulsarInstance, PulsarCluster, PulsarGateway, and KafkaCluster.                      |

`sncloud_resource_catalog` and `sncloud_resource_schema` are helper tools for the BYOC, identity, and clusters feature families. They are included when you enable a domain feature that needs schema-guided manifest authoring. Domain read tools use names such as `sncloud_clusters_read`; domain write tools use names such as `sncloud_clusters_write`.

For root and organization-level tool workflows, see [Root and Organization-Level Tools](/agent-engine/sn-remote-mcp/remote-mcp-organization-tools).

### Dynamic tooling

| Feature ID           | Alias                       | Description                                                                                                                                                                                             |
| -------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `functions-as-tools` |                             | Exposes eligible Pulsar Functions as callable MCP tools on fixed Pulsar cluster sessions.                                                                                                               |
| `agents-as-tools`    | `agents`, `agent-functions` | Accepted dynamic agent-tool feature ID. In the current preview, include `functions-as-tools` or `pulsar-admin-functions` when you want to expose eligible Orca agents on fixed Pulsar cluster sessions. |

## Examples

Bind root OAuth discovery to an organization:

```http theme={null}
X-Organization: o-sndev
```

Enable only StreamNative Cloud context tools on a root or organization endpoint:

```http theme={null}
X-MCP-Features: sncloud_context
```

Enable Pulsar topic administration and Pulsar client tools on a fixed Pulsar cluster endpoint:

```http theme={null}
X-MCP-Features: pulsar-admin-topics,pulsar-client
```

Enable dynamic Pulsar Function and Orca agent tools on a fixed Pulsar cluster endpoint:

```http theme={null}
X-MCP-Features: pulsar-admin-functions,functions-as-tools
```

Request read-only behavior from a read/write-enabled endpoint:

```http theme={null}
X-MCP-Readonly: true
```

Use API Key v2 for a non-interactive organization session:

```http theme={null}
Authorization: Bearer <api-key-v2>
X-MCP-Features: sncloud_context,sncloud_clusters
```