Tools & Permissions

When you authorize an AI tool to connect to your organization, you bind it to an organization role and choose a read or read & write access level. Both gates must pass for a capability to be available. Most authorized tools are catalog-only: they appear in the server’s capability list and are reachable through catalog helpers, but they are not all registered directly in the client’s tool list. A smaller set of common tools is directly callable. See How tools are disclosed.

​

What the role unlocks

No tools are registered if the role holds none of the gateway permissions available to it. If you connect and see “no tools available”, switch to a role that has the relevant permissions — see Connect your AI tool. If a specific capability is missing from your client’s direct tool list but your role should have it, it may be catalog-only — ask the client to search the Stardeck tool catalog (see below) rather than assuming the tool name must appear directly.

​

How tools are disclosed

This applies to the AI Integrations gateway (https://www.stardeck.ai/api/mcp), including local Claude Code connections.

• A small set of common tools is directly callable (for example session identity, knowledge store reads, data-store reads, app discovery, and cross-app calls).
• Every other authorized tool is listed by name in the server’s instructions. To use one, the client calls search_stardeck_tools for its input schema, then calls execute_stardeck_read_tool (read-only) or execute_stardeck_write_tool (state-changing) with { name, arguments }.
• Modern AI clients can follow this automatically. If you are building a direct MCP automation, do not assume every tool name is registered in tools/list — use the catalog search + execute flow for long-tail tools.

​

The tool groups

​

Knowledge store

Read and search everything in your org’s knowledge store: policies, SOPs, brand guidelines, templates, and any other reference material. Read tools: list all items, get a specific item, full-text search, list revision history. Write tools (requires agent:knowledge-store:write + read & write access): create new items, update existing content, revert to a prior version. Knowledge items have their own per-folder and per-item permissions. Even with agent:knowledge-store:read on the role, the tool can only read items the role’s knowledge permissions would normally allow. Folder-inherited permissions are respected exactly as they are in the Starcat dashboard.

​

Data stores

List data stores the connected role can access, inspect their schema, and run queries. Write tools (requires agent:data-store:write + read & write access): insert, update, delete rows; modify schema. Without a branchId, reads and writes use the store’s default database, which is usually production. Pass a branchId to work on a branch.

​

Apps

List apps in the organization and discover which endpoints expose agent-callable routes. These tools require agent:projects:read on the role. Listing apps doesn’t expose code or environment variables — only app name, slug, and which endpoints have allowAgentCalls enabled.

​

Project tasks & memory

Read and manage any app’s task list and persistent memory, addressed by app id or slug — the same work items and notes you see on each app’s dashboard. Read tools (agent:projects:read): list tasks, list and read memory entries. Write tools (agent:projects:read + read & write access): create and update tasks, write and delete memory entries. Ownership is checked per app, so the connection can only touch tasks and memory belonging to your org’s apps.

​

Project connections & deployments

Inspect how an app is wired without touching its code: list an app’s data-store connections, and read its current deployment status. Available with agent:projects:read.

​

Working on app code

Four tools turn the connection into a cross-project local development setup — clone any app in your org, run it locally, and pull Blueprint updates into forked apps. All four require agent:repos:write on the role and a read & write connection, and all only act on apps with agent development enabled (on by default per app).

• Repo access (get_repo_access) — mints a short-lived git credential for an app and returns owner, repo, default branch, and an HTTPS clone URL with the token embedded. Enough to git clone; the token expires in about an hour.
• Dev environment (get_project_dev_env) — returns the environment variables to run the app locally: its deployment identity and secret, the sandbox database URL, the control-plane URL (in the VITE_/NEXT_PUBLIC_ forms client code reads), data-store connections, and custom env vars. Values resolve to the app’s sandbox environment — writes hit shared sandbox data, never production.
• Blueprint check (get_blueprint_update) — checks whether a Blueprint-derived app has a newer published Blueprint version. If one is available, prepares a temporary fetch ref in the app’s repository and returns version details, changelog, and git merge guidance. Read-only apart from creating that ref.
• Blueprint completion (complete_blueprint_update) — called after the exact published Blueprint commit has been merged into the app’s remote main. Verifies the version and commit ancestry server-side, then records the new Blueprint baseline and a timeline event. See Update from a Blueprint for the full local workflow.

​

Platform version updates

Apps not derived from a Blueprint receive Stardeck platform updates directly, and your local AI assistant can apply them in your checkout. All three tools require agent:migration:run on the role and only act on apps with agent development enabled; preparing and completing a step also need a read & write connection. Updates go one step at a time: each step covers the versions up to the next one that needs code changes.

• Version check (get_app_version_update) — returns the app’s current and latest platform version and the state of the current step. Once a step is ready, it returns the temporary branch to merge, the code changes to make, and the exact git steps. Read-only.
• Prepare step (prepare_app_version_update) — Stardeck runs the step’s scripted changes (dependency bumps, platform files) and pushes them to a temporary platform-update/… branch in the app’s repository. Takes a few minutes; poll the version check until it’s ready.
• Complete step (complete_app_version_update) — called after you merge the branch, make the code changes, and push to main. Stardeck checks that the step’s commit and the new version are on main, records the new version, and deletes the temporary branch. If more versions remain, prepare the next step.

​

Managing Modules

The same agent:repos:write + read & write connection also lets Claude manage an app’s Modules. Each call re-checks your own access to the app, the same way the Modules tab does.

• Turn a Module on or off (set_module_enabled) — needs edit access to the app. Refuses to turn off a Module the app’s own code still imports, or the last enabled Module.
• Install or update a Module (install_module) — installs a published Module release from another app in your org and pushes it to main, then returns the integration steps to finish in your checkout. Not available for Blueprint-based apps, whose Modules come from their Blueprint.
• Detach a Module (detach_module) — org admins only. Works on feature, library and contract Modules. The whole Module becomes the app’s and stops receiving Blueprint updates. There is no undo; customize_module_ui keeps the logic on updates if you only need to change the screens. If other Modules still on Blueprint updates use it, the result warns you.
• Detach the whole app (detach_app) — org admins only. One permanent step that hands every Blueprint Module to the app, from every Blueprint it uses, and stops Blueprint updates. The first call is a dry run that changes nothing: it lists the Modules, files that differ from the Blueprint, unapplied schema changes and the version the app stays on. Claude only detaches when called again with the dry run’s confirmation token. Data stores, schema and deployments are untouched.

See Work Across Every App for the end-to-end workflow.

​

Cross-app calls

Call endpoints on your org’s apps directly from your AI tool. Useful for triggering workflows, reading app state, or posting data.

• GET requests: available with agent:cross-app:call permission and read access
• Non-GET requests: additionally require read & write access

An endpoint must have allowAgentCalls enabled in the app’s cross-app settings before it’s callable. Call rate limits and logging apply the same way they do to in-product Starcat calls.

​

Roles introspection

Look up organization roles, their permission sets, and the calling session’s own role and capabilities. Useful when the AI needs to understand what it’s authorized to do, or to answer questions about organization permissions. whoAmI reports the bound role and a list of capability labels the connected session actually holds.

​

Role management

Create, rename, and delete organization roles, and set which organization permissions a role holds (createOrgRole, updateOrgRole, deleteOrgRole, setOrgRolePermissions). These tools only appear when the person who connected is an org admin, in addition to the role holding agent:roles:write and a read & write connection. Binding the admin role to a connection is not enough. The tools can edit any role, including the one the connection is bound to, so they are limited to people who could already make the same changes in the role editor. The same safeguards as the dashboard apply: admin and external can’t be deleted, a role with members can’t be deleted, and permission keys must already exist in your org.

​

App roles & permissions

Inspect and configure an app’s deployment auth model, addressed by app id or slug: In these tool schemas, the customer-facing terms app role and team member map to the internal deployment role and organization member names. Those internal names are retained below because they describe the API fields precisely.

• get_app_auth_config — reads app permissions, app roles (deployment roles internally), role-permission assignments, default sign-up role, the team member (organization-member) access policy, and project-specific organization-role grants
• set_app_auth_config — declaratively sets that app auth configuration (permissions, roles, assignments, default sign-up role, and team member access policy)
• set_app_org_role_grants — replaces which app permissions each listed organization role holds for that app

Read tools require agent:deployment-auth:read. Write tools additionally require agent:deployment-auth:write and read & write access.

​

App sign-in branding

Read and update the branding of an app’s hosted sign-in page (logo, primary/background colors, heading and subheading text), addressed by app id or slug:

• get_app_signin_branding — reads the current sign-in page branding
• set_app_signin_branding — partially updates branding fields (pass null to clear a field)

The Powered by Stardeck footer is always shown and is not customizable. Read tools require agent:signin-branding:read. Write tools additionally require agent:signin-branding:write and read & write access.

​

Domains & DNS

List your organization’s domains and manage DNS records on domains registered through Stardeck:

• list_domains — every domain with its type, status, assigned app, and whether its DNS is editable here
• list_dns_records — a registered domain’s DNS records, with Stardeck-maintained records marked managed
• create_dns_record, update_dns_record, delete_dns_record — add, change, or remove A, AAAA, CNAME, MX, TXT, NS, SRV, and CAA records

Connected domains keep their DNS at your own registrar, so these tools can’t edit them. Records Stardeck maintains for app routing and email can’t be changed or deleted. Read tools require agent:domains:read. Write tools additionally require agent:domains:write and read & write access.

​

Errors & worker logs

Debug a deployed app from your local checkout, addressed by app id or slug:

• list_project_errors — the app’s errors reported to Sentry, grouped by issue, with environments, occurrence counts, and first/last seen. Filter by status and by environment (production, preview, or sandbox — sandbox also covers local runs using get_project_dev_env).
• get_project_error_details — one issue’s exception, stacktrace with source context, breadcrumbs, and request, taken from this app’s own latest occurrence.
• get_worker_logs — runtime logs from the app’s deployed worker, production or a branch preview: console output, status codes, and unhandled errors, up to 3 days back.
• set_project_error_resolved — marks every occurrence of an issue in this app resolved, or reopens it. Needs a read & write connection.

All four require agent:sentry:read. They only read and change the app’s own error records, the same ones the app’s monitoring tab shows.

​

Uptime monitors

List an app’s uptime monitors and report schedule (list_app_uptime_monitors, get_app_uptime_report_settings) with agent:uptime:manage. With a read & write connection, also create, update, pause, and delete monitors and change the report schedule. Creating a monitor needs uptime monitoring on your plan.

​

Google Sheets syncs

Set up the platform-managed sync between a spreadsheet tab and a Data Store table, addressed by app id or slug:

• get_sheet_sync_context — the Google accounts granted to the app and the syncs it already has. Call it first.
• inspect_spreadsheet — a spreadsheet’s tabs, or one tab’s headers and a few sample rows.
• configure_sheet_sync — creates or updates a sync. The whole configuration is checked against the real tab and table before it is saved, and errors name the header, column, or tab that is wrong.
• delete_sheet_sync — stops a sync. The table and spreadsheet are left as they are.

Read tools require agent:sheet-syncs:read; configure and delete require agent:sheet-syncs:write and read & write access. Only Google accounts granted to the app can be used, and syncs a person set up with their own Google account can’t be changed or removed from here.

​

Skills

Discover Stardeck’s built-in skills — focused guides for using platform features. The AI tool can load these as content to apply them in context.

​

Choosing a role

Use the least privilege that covers your use case: You can change the role at any time from Settings → AI Integrations without re-authorizing.

​

Security model

The connection is double-gated: the OAuth scope (set at authorization) limits what can happen broadly, and the role’s permissions narrow it further per tool group. Both gates are enforced fresh on every request — not just at connection time. This means:

• Removing a permission from a role takes effect on the next tool call
• Removing someone from the team revokes their connection immediately
• Changing the role from the AI Integrations tab takes effect on the next request — no new token needed

​

Next steps