Skip to main content
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.
  • Either an interactive user login that supports OAuth 2.1 or a service account API key with MCP permissions.
  • 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.
  • Service account API keys — supply the key ID and secret to 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

  • StreamNative Cloud exposes a root entry point at https://mcp.streamnative.cloud and publishes cluster-specific endpoints beneath it.
  • Build the cluster endpoint as /mcp/x/<organization>/<pulsar-instance>/<cluster-name>. For example, organization o-sndev, instance instance-1, cluster c-cluster resolves to https://mcp.streamnative.cloud/mcp/x/o-sndev/instance-1/c-cluster.
  • Provide the cluster endpoint to your MCP client so tool discovery and authorization scope to the intended cluster.

​
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 cluster endpoint (for example, https://mcp.streamnative.cloud/mcp/x/o-sndev/instance-1/c-cluster) and follow the client’s instructions for either OAuth 2.1 or API key authentication.
  • Provide the desired StreamNative Cloud cluster context when prompted; the server scopes tool discovery to that context.
  • 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.

​
Troubleshooting

  • 401 Unauthorized — confirm the account or service key includes the required MCP permissions and that the token has not expired.
  • Empty tool list — ensure the selected cluster has tools enabled and that your identity can access them.
  • Connection drops — the preview service enforces idle timeouts. Reconnect or configure your client to reconnect automatically.