NovaOS MCP
Field guide

Service accounts and calling agents from an app backend

Creating and rotating service accounts, scopes, token minting, run-as-user vs service account, capacity limits and the backend integration pattern.

Create a service account (Org Console)

  1. Owner/Tenant admin: Org Console > Manage > Service Accounts (platform admins: Platform Admin > Service Accounts). Create the account; machine role sa-executor (or the org's executor role).
  2. Account page sections: Agents (Install agent), Permissions, Runs, Usage, Secret & Rotation.
  3. Create the credential and copy client id + secret (secret shown once) into a local secret file (novaos_sa_credentials_file), never into chat or git.
  4. Grant scopes/permissions (below) and, for write-classified MCP tools, an exact-tool SA grant.
  5. Agents > Install agent for the account itself (a personal install does not count). Read back version + Instance ID.
  6. Test: novaos_sa_token_test, then novaos_ask_agent {as: "<ref>", message: {"skill":"ping"}}. Guided: novaos_workflow_start {"workflow":"connect_backend"}.

Scopes for service accounts

  • Basic call: agent:execute agent:read (NOT MCP tools or models).
  • Models: llm:model:* (or llm:model:<id>) AND the agent manifest lists llm in permissions.tools.
  • MCP tools: mcp:tools:* or mcp:tools:<category> (registered category).
  • Knowledge: rag:query rag:collections:read (+ rag:parse rag:ingest rag:collections:write to ingest).
  • REST connectors: connector:invoke + connector:<source>:<operation>. Memory: memory:{read,write,delete}:{run,task,agent} (SA tokens cannot call the Memory service directly).
  • After a role/permission change, mint a NEW token: cached tokens keep old rights. Check token_response["scope"] contains what you need.

Token

POST {iam}/oidc/token  (form)
grant_type=client_credentials client_id=... client_secret=... resource=urn:novaos organization_id=<org> scope=<space separated>

Both resource and organization_id are mandatory (else a silent 403). TTL ~15 min: cache and refresh 60 s early; refresh once on 401. invalid_client = wrong id/secret or expired secret.

Rotation

Secret & Rotation shows Issued at, Expires at, policy and history; Rotate secret. Procedure: rotate -> update the backend secret store -> mint a fresh token -> test one request -> retire the old secret.

Running agents from a backend

  • POST {gateway}/api/v1/execute {instance_id, input: "<string>", thread_id?, skill?} + X-Idempotency-Key (and body idempotency_key). Works with SA tokens on FDE 2.1 (undocumented) and is the only path on fde-us / staging-eu.
  • POST /api/v1/service/runs (skill_id field, SSE with Accept: text/event-stream) exists only where the gateway has SA_EXECUTION_ENABLED (404 on fde-us, staging-eu, prod-eu). Prefer execute.
  • /a2a/v1/agents/{agent_id} direct A2A: SA only, same restriction.
  • The gateway derives the run id from idempotency key + thread: re-opening with the same key joins the running run. One key per turn; a new key only after a run NovaOS reports failed.
  • Never retry a timeout (the run may still execute; a resend queues a duplicate turn). A 429 or a dispatch failure starts no run: safe to retry. Details of streaming/recovery: guide 08-runs-streaming. Generated client code: novaos_app_integration_code.

Run as the user vs as the service account

  • User-triggered runs: the SPA signs in with Logto (PKCE, org-scoped urn:novaos token with agent/mcp/llm/rag scopes), sends X-NovaOS-User-Token to your backend on EVERY run-starting request (else user_token_missing); the backend resolves/installs the user's own instance (cache per org+user+agent+version; re-resolve once on INSTANCE_NOT_FOUND).
  • User runs cannot call write-classified MCP tools (-32042): use returned writes (persistence: "return").
  • Background, scheduled and recovery work stays on the SA. Long user runs outlive the user token: keep a renewable grant; never silently fall back to the SA for user-visible actions.

Capacity and limits

  • ~8 concurrent service-account runs per org: HTTP 429 CONCURRENCY_LIMIT_EXCEEDED / ConcurrencyLimitError ("Maximum concurrent service_account runs (8) reached"). The slot is held while the SSE stream is open. Back off: Retry-After (clamp 1-10 s) else 3 s doubling to 10 s + jitter, 60 s budget, show "Waiting for capacity".
  • Pod quota: the open returns 200, then a 403 event exceeded quota: namespace-quota ... pods=150 (~1 GiB per pod). Show "The platform is at capacity, try again in a few minutes" (no immediate retry). Consider an app-side run gate (e.g. 15 in flight, 3 per user).
  • A pod = (user, instance, config) and serves one run at a time; a concurrent run takes a new cold pod (20-45 s; first message ~25 s cold vs ~6 s warm). Idle TTL ~10 min, max ~1 h. Fewer, bigger runs beat many small ones.
  • Per-installation limits (install form): timeout, requests/second, requests/minute, concurrency, allowed domains. Tenant rate limits (RPM, TPM, RPD, concurrency) are set by platform admins at Platform Admin > Rate Limits.

Multi-org

Store per org: SA client id + secret REFERENCE (secret manager name, never the secret), instance id. Every component that talks to NovaOS needs the org id configured (else 403 "organization is not served by this deployment").