Tools & Permissions

A connection is bound to an organization role and an access level (Read only or Read & write). A tool is available only when both allow it. Tools that act on an app take its id or slug.

What the role unlocksCopy Anchor Link

"Read & write?" means the write tools in that group need a Read & write connection. Read tools work on either.

If the role holds none of these permissions, the connection has no tools. Switch roles on the Agents page.

How tools are disclosedCopy Anchor Link

This applies to every connection to https://www.stardeck.ai/api/mcp, including local coding agents.

• A small set of common tools is directly callable: session identity, the development guide (get_platform_development_guide), knowledge store reads, the main data-store tools, app discovery, cross-app calls, and skills.
• Every other authorized tool is catalog-only: listed by name in the server's instructions. The client calls search_stardeck_tools for its schema, then execute_stardeck_read_tool or execute_stardeck_write_tool with { name, arguments }.
• Modern AI clients do this on their own. If you build a direct MCP automation, don't assume every tool is in tools/list.

Rules worth knowingCopy Anchor Link

Data storesCopy Anchor Link

Without a branchId, reads and writes use the store's default database, which is usually production. Pass a branchId to work on a branch.

An app you run locally reads whatever the sandbox is routed to. A new app routes every environment to the default database, so its sandbox and production share data until you split them:

• See where each environment points with getProjectDataStoreEnvironments, and list branches with listDataStoreBranches. Pass the sandbox's branch as branchId.
• To give the sandbox its own data: createDataStoreBranch, then setDataStoreEnvironmentMapping. clearDataStoreEnvironmentMapping undoes it.
• diffProjectDataStoreEnvironments shows what promoting the sandbox schema would change.
• Routing changes need Admin access on the store and run without a confirmation, production included.

Knowledge storeCopy Anchor Link

Per-folder and per-item knowledge permissions still apply on top of agent:knowledge-store:read.

Deploying appsCopy Anchor Link

• A production deploy_app answers its first call with a preview: the exact commit, and the pending schema changes it will apply, destructive ones included. It deploys only when your agent calls again with the confirmToken, after you confirm. A preview or staging deploy runs on the first call. Every deploy ships the branch's GitHub head and applies pending schema changes for that environment.
• The deploy is pinned to the commit it started from. A production deploy only approves destructive changes pending at start. Ask your agent to skip schema changes to ship code only.
• A branch pushed straight to GitHub needs track_app_branch before it has a preview. Tracking builds nothing. Needs the Branches feature.
• deploy_app with environment: "staging" creates a staging: a 24-hour copy on a fresh copy of production data, where sends are captured. list_app_stagings lists an app's stagings (with the id of the newest build and of the one serving), get_project_deployment_status, list_project_deployment_revisions and get_project_deployment_logs read a staging's builds when you pass environment: "staging" and its stagingDeploymentId, list_app_staging_captured_sends and get_app_staging_captured_send read what they captured (long bodies are cut), and delete_app_staging removes one. None of them asks for confirmation.

Working on app codeCopy Anchor Link

These need agent:repos:write and Read & write, except list_app_modules, which needs only agent:projects:read. Most act only on apps with agent development enabled (on by default); restart_sandbox and set_up_blueprint_app don't need it.

The last three rows appear only on a connection bound to the Admin role.

Platform version updates (get_app_version_update, prepare_app_version_update, complete_app_version_update) apply to older apps that predate the shared foundation, one step at a time.

See Work Across Every App.

App settingsCopy Anchor Link

• Covers general, sign-in, environment variables (non-secret only), domain, cross-app, integrations, payments, members and invites, app roles, repository, updates, data-store access, AI proxy, schedules, Edge devices, lifecycle, branches, and logs.
• Every change shows a preview and runs only after you confirm.
• Your AI tool can only do what you can do on that app. Deleting or transferring an app also needs Manage Apps.
• Never done by an AI tool: entering secrets, third-party consent screens (Stripe, LINE, Slack, email), receipt logo upload, passwords, invite links. get_app_settings_handoff returns the dashboard link instead.

App roles & permissionsCopy Anchor Link

get_app_auth_config, set_app_auth_config, and set_app_org_role_grants read and set an app's permissions, app roles, role assignments, default sign-up role, team member access, and org-role grants. In the tool schemas, app role and team member appear as deployment role and organization member.

Opening an app in your browserCopy Anchor Link

Your agent can sign its browser tool in to one of your apps to click through it, check a fix, or reproduce a bug. Set it up once:

1. An org admin turns on Allow agents to access under Settings → Team Members. It is off by default. The browser signs in as Stardeck's agent account, agents@stardeck.ai, which this switch adds to your organization.
2. Connect with Read & write. A Read only connection never gets these tools.
3. Bind the connection to a role with Open Apps in a Browser (agent:app-browser:open). To open an app as another person or role, the role also needs Open Apps as Another Person or Role (agent:app-browser:assume), and you must be an org admin. Both start on the Admin role only; add them to another role under Settings → Roles & Permissions.
4. Give your agent a browser tool: for example the Playwright MCP server (claude mcp add playwright npx @playwright/mcp@latest in Claude Code), Claude in Chrome, or Cursor's browser. Stardeck doesn't provide one.

Then ask, for example, "Open the storefront staging in your browser as the cashier role and check checkout."

• Staging by default. Without a deploymentId, it opens the app's only active staging. If there is none, or more than one, your agent is told to choose one. Production opens only with production: true, also when you name the production deployment. It never falls back to production.
• One app, one deployment, one identity. The browser can't reach your dashboard, another app or another deployment, and can't switch person or role inside the app. Ask again for something else.
• The link is like a password. It works once, within 60 seconds. Your agent opens it in its own browser tool and should never paste it into chat, code, logs or tickets: whoever opens it first is signed in.
• 30 minutes. The browser stays signed in for 30 minutes at most. It is signed out sooner when the connection is revoked or reconnected, its role or access level changes, the role loses either permission, you leave the organization or (when opened as someone else) are no longer an org admin, the app or organization role it was opened as is disabled, or Allow agents to access is turned off. Only that connection's sign-ins end; your other connections keep theirs. Once you revoke a connection, nothing it was given before works again, even after you reconnect it: reconnecting starts fresh. A browser only ever opens with the role and access level you chose when you last connected that client. A connection set up before browser sign-in existed has to be reconnected once.
• Disabled roles. A disabled role isn't offered and can't be opened, by an agent or by an admin previewing the app.
• Limits. Each connection can ask for 20 sign-ins an hour, each person 40 across their connections, and each organization 200. A connection can have 5 open at once, an organization 50. Past a limit your agent is told when to try again.
• What the browser does is real. Clicks in the app run the app's own code, so they don't ask for the confirmations your connection's write tools do, and production data changed through the app is changed. On a staging, sends are captured and payments use the playground, but app code that calls a third party with its own key still makes that call. See What still happens.
• Recorded. Each sign-in records who asked, through which connection, for which deployment and as whom.

This is separate from Starcat, which signs in through access a Stardeck teammate approves for it.

Other rulesCopy Anchor Link

• Role management and Team members changes appear only when the person who connected is an org admin. admin and external roles, and roles with members, can't be deleted. Every team change confirms first.
• Support conversations: a reply reaches the customer on their channel and can't be unsent, so it confirms first.
• Customer directory also needs Manage Identities; archive, merge, and membership tools need Govern Identities and confirm first.
• DNS: connected domains keep DNS at your registrar. Stardeck-managed records can't be changed.
• Cross-app calls follow the same rate limits and logging as Starcat's.

Choosing a roleCopy Anchor Link

Security modelCopy Anchor Link

Roles and access levels are checked on every call. See Security model.

Next stepsCopy Anchor Link