Tools & Permissions

When you authorize an AI tool to connect to your org, you bind it to an org 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 org-level AI Integrations gateway (https://www.stardeck.ai/api/mcp), not the project-scoped Claude Code gateway.

• 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. Writes target the store’s configured agent branch — if that branch is production, writes go to production.

​

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.

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 org 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 org permissions. whoAmI reports the bound role and a list of capability labels the connected session actually holds.

​

App roles & permissions

Inspect and configure an app’s deployment auth model, addressed by app id or slug:

• get_app_auth_config — reads deployment permissions, deployment roles, role-permission assignments, default sign-up role, organization-member access policy, and project-specific org-role grants
• set_app_auth_config — declaratively sets that deployment auth configuration (permissions, roles, assignments, default sign-up role, and org-member access policy)
• set_app_org_role_grants — replaces which deployment 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.

​

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’s org membership revokes their connection immediately
• Changing the role from the AI Integrations tab takes effect on the next request — no new token needed

​

Next steps