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.

This page explains how to reach the managed StreamNative MCP Server during the preview program. Use it when you want to consume StreamNative-managed tools without hosting the server yourself.

​
Prerequisites

  • A StreamNative Cloud account with access to the organization, tenant, and clusters you plan to explore.
  • The MCP Server preview feature enabled for your organization and for any clusters you want to expose. See Governance & Permissions.
  • Either an interactive user login that supports OAuth 2.1 or an API Key v2 for a service account with MCP permissions. Root and organization endpoints require an AuthV2 organization audience (urn:sn:cloud:<organization>).
  • An MCP-compatible client, such as VS Code, an Orca agent, or any runtime that speaks the Model Context Protocol.

​
Authenticate with StreamNative Cloud

You can sign in through two supported flows:
  • OAuth 2.1 - ideal for IDEs. Initiate the sign-in from the client, approve the scopes in your browser, and the session token is stored by the IDE. For root endpoint OAuth, send X-Organization when the client supports custom headers, or select the organization in the browser sign-in flow.
  • Service account API keys - send an API Key v2 as a bearer token from clients that run outside the browser (for example, CI/CD automation or headless agents). Rotate keys through the StreamNative Cloud Console.

​
Choose the right endpoint

Do not connect directly to https://mcp.streamnative.cloud. Use one of the MCP paths shown below.
ModeEndpointUse when
Roothttps://mcp.streamnative.cloud/mcpYour client should connect to the shared root path and let the server resolve the organization from the AuthV2 organization audience. For OAuth discovery, send X-Organization: <organization> or select the organization during sign-in. For bearer tokens, the token must contain exactly one organization audience.
Organizationhttps://mcp.streamnative.cloud/mcp/x/<organization>You want organization-level tools first, including cluster discovery, cluster switching, and StreamNative Cloud control-plane tools.
Fixed clusterhttps://mcp.streamnative.cloud/mcp/x/<organization>/<instance>/<cluster>You want one stable Pulsar or Kafka cluster context, a cluster-scoped tool catalog, and support for dynamic Pulsar Function or Orca agent tools.
For example, organization o-sndev, instance instance-1, and cluster c-cluster resolves to https://mcp.streamnative.cloud/mcp/x/o-sndev/instance-1/c-cluster. For root and organization-level workflows, see Root and Organization-Level Tools.

​
Connect from Orca Engine runtimes

  • Configure managed tools via snctl when submit agents.
  • When you deploy with snctl agents create ... --agent-tools-config, Orca Engine authenticates to the remote MCP server with the service account already assigned to the agent runtime. This keeps cluster access scoped to the permissions you granted that service account.
  • Redeploy or restart agents that depend on remote MCP tools so the runtime attaches the new connection metadata.
  • The Orca engine runtime automatically watches for tools changed notifications and reloads the agent if the remote catalog diverges from the cached copy.

​
Use from other MCP clients

  • Set the remote host to the root, organization, or cluster endpoint and follow the client’s instructions for either OAuth 2.1 or API key authentication.
  • For API key authentication, send Authorization: Bearer <api-key>. Use API Key v2 for root and organization endpoints because they require organization-scoped authentication.
  • For root endpoint OAuth discovery, send X-Organization: <organization> when your client supports custom headers. If your client cannot send this header, the interactive OAuth flow lets you select an organization during sign-in. If both the token and the header provide an organization, they must match.
  • Optionally send X-MCP-Features to narrow the tool catalog and X-MCP-Readonly to request read-only behavior. These headers are evaluated per session and cannot grant tools beyond administrator-configured allow lists. See Remote MCP Headers and Feature Selection.
  • Persist refresh tokens or API keys according to your organization’s security policies. Delete unused sessions from the StreamNative Cloud console.
  • In VS Code, follow the Use MCP servers in VS Code to enable MCP.

​
Example: connect with API Key v2 and custom headers

Use a root endpoint when the client can send X-Organization, or use an organization endpoint when you want the organization bound in the URL. 
curl -N https://mcp.streamnative.cloud/mcp \
  -H "Authorization: Bearer <api-key-v2>" \
  -H "X-Organization: o-sndev" \
  -H "X-MCP-Features: sncloud_context,sncloud_clusters" \
  -H "X-MCP-Readonly: true" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json"
Use the same headers in MCP clients that support custom HTTP headers. If a client cannot send X-Organization, prefer the organization endpoint https://mcp.streamnative.cloud/mcp/x/<organization>.

​
Troubleshooting

  • 401 Unauthorized - confirm the account or API Key v2 includes the required MCP permissions and that the token has not expired.
  • 403 Forbidden on /mcp - confirm the bearer token contains exactly one AuthV2 organization audience and that X-Organization, when present, matches that audience.
  • Root OAuth discovery fails - send X-Organization: <organization> when the client supports custom headers, or retry with an interactive client that can complete the organization picker flow.
  • Empty tool list - ensure MCP is enabled for the organization and target cluster, the selected feature set is not empty, and your identity can access the resources.
  • Connection drops - the preview service enforces idle timeouts. Reconnect or configure your client to reconnect automatically.