Tools: access, settings and integrations
Access
get_access
Who can open the project's app: the mode, the people and groups allowed, app roles, and what the live team / department rules resolve to now.
| Input | Type | Required |
|---|---|---|
project | string | Yes |
set_access
Changes who can open the app. Owner, project developers or an Org Admin; audited. Omitted fields keep their current value.
| Input | Type | Required | Description |
|---|---|---|---|
project | string | Yes | |
mode | "only_me" | "team" | "department" | "groups" | "everyone" | No | See below |
members | string[] | No | People and groups for groups mode. Replaces the list. |
roles | Record<string, string[]> | No | App roles, e.g. { "approver": ["Finance - FP&A"] }. They reach the app in the X-TC-User token's roles claim. |
A member is a user email (megan.bowen@contoso.com), a group name ("Finance - FP&A") or a directory object id.
| Mode | Who can open the app |
|---|---|
only_me | The owner only (default for new projects) |
team | The owner's manager's direct reports, resolved live from the directory |
department | The owner's department, live |
groups | The owner plus members |
everyone | Anyone in your organization (your company's directory) |
Returns the new access settings; the summary reads "expenses can now be opened by the owner + Operations".
Settings
list_env
The project's environment variables. Secret values are never returned (they're masked); plain values are. pendingRedeploy means there are changes the running app doesn't have yet.
| Input | Type | Required |
|---|---|---|
project | string | Yes |
set_env
Adds, changes or removes environment variables. Owner, project developers or an Org Admin; audited by name only. Values are stored encrypted, and secrets are write-only afterwards. Names starting with TC_, and DATABASE_URL and PORT, are reserved.
| Input | Type | Required | Description |
|---|---|---|---|
project | string | Yes | |
vars | { name, value, secret? }[] | No | Variables to add or change |
unset | string[] | No | Names to remove |
redeploy | boolean | No | Redeploy the current production build now (no rebuild) so the app sees the change |
Pass at least one of vars, unset or redeploy: true, otherwise you get NOTHING_TO_DO.
Returns { env, redeployed }.
delete_project
Deletes a project for good: the app, preview URLs, Data API, database, files and grants. Pending access requests are cancelled, an audit record is kept, and the name becomes free. Owner or org admin only.
| Input | Type | Required | Description |
|---|---|---|---|
project | string | Yes | |
confirm | string | Yes | The exact project name, typed by the person to confirm |
Irreversible. Agents should ask the person first, and suggest archiving if they might want the app back. A confirm that doesn't match returns CONFIRM_MISMATCH.
Integrations and access requests
See Integrations for how grants and approvals work.
list_integrations
Integrations IT has connected and enabled.
Input: none.
Returns an array of { name, displayName, mode, how, maxScopes, approvers, description }. name is what app code uses in tc.int.<name>.
describe_integration
How to call one integration from app code (SDK and raw paths), its scopes and who approves them.
| Input | Type | Required |
|---|---|---|
name | string | Yes |
Returns the integration plus a usage hint, for example for salesforce: tc.int.salesforce.get('/query', { q: … }).
Errors: INTEGRATION_NOT_FOUND.
request_grant
Asks for integration access for a project (owner or org admin), or, with share_file, asks to show a Microsoft 365 file's data to everyone who can open the app. Policies may approve it at once; otherwise it's routed to the integration's approvers (and the manager, for sharing) with a Teams card.
| Input | Type | Required | Description |
|---|---|---|---|
project | string | Yes | |
integration | string | With scopes | e.g. salesforce, graph, erp, teams |
scopes | string[] | With integration | e.g. ["Case:read", "Account:read"] |
identity | "user" | "project" | No | user (default): as each signed-in user. project: as the app itself (jobs, snapshots). |
purpose | string (3–500) | Yes | One line for approvers, in the person's words |
share_file | string | No | A SharePoint URL whose data should be visible to everyone with app access. The request states how many viewers can't open the file today. |
Returns { status, autoApproved, request, grant }. status is covered (already granted), granted (approved by a policy), pending or denied. With share_file, it returns { request, autoApproved }.
Errors: BAD_REQUEST without integration + scopes or share_file; READ_ONLY / PROJECT_NOT_FOUND if you can't manage the project.
list_requests
Access requests for a project, or all of yours: status, scopes, approvers, the decision (approved narrower, or denied with a reason) and questions from approvers.
| Input | Type | Required | Description |
|---|---|---|---|
project | string | No | Default: every request you made |
status | "pending" | "approved" | "denied" | "withdrawn" | "all" | No | Default: all |
Returns an array of { id, status, project, integration, scopes, identity, summary, approvers, decision, messages, url }, where url opens the request in the console.