> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stardeck.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Tools & Permissions
> What your connected AI tool can do, and how the role and access level control it.
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](#how-tools-are-disclosed).
## What the role unlocks
| Tool group | Required role permission | Required access level |
| ------------------------------------- | ----------------------------- | --------------------- |
| **Knowledge store — read** | `agent:knowledge-store:read` | Read |
| **Knowledge store — write** | `agent:knowledge-store:write` | Read & write |
| **Data stores — read** | `agent:data-store:read` | Read |
| **Data stores — write** | `agent:data-store:write` | Read & write |
| **Apps (list & discover)** | `agent:projects:read` | Read |
| **Project tasks & memory — read** | `agent:projects:read` | Read |
| **Project tasks & memory — write** | `agent:projects:read` | Read & write |
| **Project connections & deployments** | `agent:projects:read` | Read |
| **Repo access (clone credentials)** | `agent:repos:write` | Read & write |
| **Dev environment (run locally)** | `agent:repos:write` | Read & write |
| **Blueprint updates** | `agent:repos:write` | Read & write |
| **Cross-app calls — GET** | `agent:cross-app:call` | Read |
| **Cross-app calls — non-GET** | `agent:cross-app:call` | Read & write |
| **Roles introspection** | `agent:roles:read` | Read |
| **App roles & permissions — read** | `agent:deployment-auth:read` | Read |
| **App roles & permissions — write** | `agent:deployment-auth:write` | Read & write |
| **App sign-in branding — read** | `agent:signin-branding:read` | Read |
| **App sign-in branding — write** | `agent:signin-branding:write` | Read & write |
| **Skills** | `agent:skills:execute` | Read |
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](/ai-integrations/connect).
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](/local-claude-code/tools).
* 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.
Data store write access changes live data. Pick the least permissive role that gets the job done,
and prefer read-only when write access isn't needed.
### 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](/local-claude-code/blueprint-updates) for the full local workflow.
These return real credentials and decrypted secrets. Grant `agent:repos:write` only to roles that
need to develop app code locally, and only over connections you trust with a checkout of the code.
See [Work Across Every App](/local-claude-code/cross-project) 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:
| Use case | Suggested role |
| ----------------------------------------- | ------------------------------------------------------------------- |
| Answer questions from the knowledge store | Role with `agent:knowledge-store:read` only |
| Query data + answer questions | Role with `agent:data-store:read` + `agent:knowledge-store:read` |
| Read and write data + operate apps | Role with data-store read/write + `agent:cross-app:call` |
| Develop app code locally across apps | Role with `agent:repos:write` + `agent:projects:read`, read & write |
| Full org access | Admin role (holds all permissions) |
You can change the role at any time from **[Settings → AI Integrations](https://www.stardeck.ai/dashboard/settings?tab=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
Step-by-step setup for each supported client
Create and configure the role for your connection
How data stores work and how access grants are configured
Enable agent-callable endpoints on your apps