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, organizationo-sndev
, instanceinstance-1
, clusterc-cluster
resolves tohttps://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.