Built-in MCP server providing tools for managing Archestra platform resources
107 min read
The Archestra MCP Server is a built-in MCP server that ships with the platform and requires no installation. It exposes tools for managing platform resources such as agents, MCP servers, policies, and limits.
Most tools require explicit assignment to Agents or MCP Gateways before they can be used. The following tools are pre-installed on all new agents by default: todo_write, query_knowledge_sources.
All Archestra tools are prefixed with archestra__. Most built-in tools are always trusted — they bypass tool invocation and trusted data policies.
query_knowledge_sources is an exception: its output is treated as sensitive by default and is evaluated by trusted data policies. See AI Tool Guardrails for more details.
query_knowledge_sources is evaluated by trusted data policies and its results are treated as sensitive by default.
However, RBAC (role-based access control) is still enforced. Every tool is mapped to a required permission (resource + action). The tools/list endpoint dynamically filters tools so users only see tools they have permission to use. For example, a user without knowledgeSource:create permission will not see create_knowledge_base in their tool list and cannot execute it.
Some tools enforce an additional access requirement in their handler beyond this RBAC permission — for example, the team membership tools gate on team:read but then require the caller to be an organization-level team manager or an admin (team-member role) of the specific team. These tools are marked with a † in the tables below, and the requirement is spelled out in each tool's details.
Tools Reference
Identity
Tool
Description
Required RBAC Permission
whoami
Returns the name and ID of the current agent.
None (no additional RBAC permission required)
whoami
Required RBAC permission: None (no additional RBAC permission required)
This tool takes no arguments.
Output
Field
Type
Required
Description
agentId
string
Yes
The ID of the current agent.
agentName
string
Yes
The display name of the current agent.
Agents
Tool
Description
Required RBAC Permission
create_agent
Create a new agent with the specified name, optional description, labels, prompts, icon emoji, explicit tool assignments, and sub-agent delegations.
agent:create
get_agent
Get a specific agent by ID or name.
agent:read
list_agents
List agents with optional filtering by name.
agent:read
edit_agent
Edit an existing agent.
agent:update
create_agent
Required RBAC permission: agent:create
Input
Parameter
Type
Required
Description
name
string
Yes
Name for the new resource.
scope
"personal" | "team" | "org"
No
Visibility scope. Defaults to personal for agents and org for LLM proxies/MCP gateways unless teams are provided.
labels
object[]
No
Optional key-value labels for organization and categorization.
labels[].key
string
Yes
labels[].value
string
Yes
teams
string[]
No
Team IDs to attach when creating a team-scoped resource.
toolExposureMode
"full" | "search_and_run_only"
No
How tools should be loaded for MCP clients and models. Use 'search_and_run_only' to keep the initial tool list small while letting search_tools find assigned tools and run_tool execute them. Assigned skill discovery/loading tools (list_skills, load_skill), sandbox runtime tools (run_command, download_file, upload_file) — when the code runtime is enabled and assigned — and persistent-files tools (search_files, read_file, save_file, edit_file, delete_file) — when the Projects feature is enabled and assigned — stay directly available in both modes. App tools (scaffold_app, edit_app, read_app, render_app, list_apps, and the rest of the app surface) are reached through search_tools/run_tool in 'search_and_run_only' mode.
accessAllTools
boolean
No
Allow dynamic tool access: search_tools/run_tool may discover and run any tool the calling user can access (MCP catalog tools and knowledge sources) without assigning it to the agent. Enabling this forces toolExposureMode to 'search_and_run_only', since dynamic access only works through the search/run dispatch surface. Defaults to false. Also gated by the organization's security settings.
accessAllSubagents
boolean
No
Allow dynamic subagent delegation: the agent may delegate to any internal agent the calling user can access, beyond explicitly-configured delegation targets (minus subagent exclusions). Defaults to false.
description
string | null
No
Optional human-readable description of the agent.
icon
string | null
No
Optional emoji icon for the agent.
knowledgeBaseIds
string[]
No
Knowledge base IDs to assign to the agent. Use get_knowledge_bases first when you need to look up IDs by name.
connectorIds
string[]
No
Knowledge connector IDs to assign directly to the agent. Use get_knowledge_connectors first when you need to look up IDs by name.
subAgentIds
string[]
No
Agent IDs to delegate to from this newly created agent.
suggestedPrompts
object[]
No
Optional suggested prompts that appear in the chat UI.
suggestedPrompts[].summaryTitle
string
Yes
Short title shown to users for this suggested prompt.
suggestedPrompts[].prompt
string
Yes
Suggested prompt text users can click to start a conversation.
systemPrompt
string | null
No
The system prompt that defines the agent's behavior.
toolAssignments
object[]
No
Explicit tool assignments to create immediately after the agent is created.
toolAssignments[].toolId
string
Yes
The ID of the tool to assign to the agent.
toolAssignments[].resolveAtCallTime
boolean
No
When true, resolve credentials and execution target at tool call time. Prefer this for builder flows.
toolAssignments[].credentialResolutionMode
"static" | "dynamic" | "enterprise_managed"
No
toolAssignments[].mcpServerId
string | null
No
Optional MCP server installation to pin the tool to when using static credential resolution.
get_agent
Required RBAC permission: agent:read
Input
Parameter
Type
Required
Description
id
string
No
The ID of the agent to fetch. Prefer the ID when you already have it.
name
string
No
The exact name of the agent to fetch when you do not already have the ID.
Output
Field
Type
Required
Description
id
string
Yes
The resource ID.
name
string
Yes
The resource name.
description
string | null
Yes
The resource description, if any.
icon
string | null
Yes
The emoji icon, if configured.
scope
"personal" | "team" | "org"
Yes
The visibility scope.
toolExposureMode
"full" | "search_and_run_only"
Yes
How tools are loaded for MCP clients and models.
accessAllTools
boolean
Yes
Whether search_tools/run_tool may dynamically access every tool the calling user can access.
accessAllSubagents
boolean
Yes
Whether the agent may delegate to every internal agent the calling user can access.
agentType
"agent" | "llm_proxy" | "mcp_gateway" | "profile"
Yes
The resource type.
systemPrompt
string | null
No
teams
object[]
Yes
The teams attached to it.
teams[].id
string
Yes
The team ID.
teams[].name
string
Yes
The team name.
labels
object[]
Yes
Assigned labels.
labels[].key
string
Yes
The label key.
labels[].value
string
Yes
The label value.
tools
object[]
Yes
Assigned tools.
tools[].id
string
Yes
The assigned tool ID.
tools[].name
string
Yes
The tool name.
tools[].description
string | null
Yes
The tool description, if any.
tools[].catalogId
string | null
Yes
The MCP catalog ID the tool comes from, if any.
knowledgeBaseIds
string[]
Yes
Assigned knowledge base IDs.
connectorIds
string[]
Yes
Assigned knowledge connector IDs.
suggestedPrompts
object[]
Yes
Configured suggested prompts.
suggestedPrompts[].summaryTitle
string
Yes
The short title shown in the chat UI.
suggestedPrompts[].prompt
string
Yes
The suggested prompt text.
list_agents
Required RBAC permission: agent:read
Input
Parameter
Type
Required
Description
limit
integer
No
Maximum number of agents to return.
name
string
No
Optional agent name filter. Use this when the user names an agent but you still need to look up the ID.
Output
Field
Type
Required
Description
total
number
Yes
The total number of matching agents.
agents
object[]
Yes
agents[].id
string
Yes
The agent ID.
agents[].name
string
Yes
The agent name.
agents[].scope
"personal" | "team" | "org"
Yes
The agent scope.
agents[].description
string | null
Yes
The agent description, if any.
agents[].teams
object[]
Yes
Teams attached to it.
agents[].teams[].id
string
Yes
The team ID.
agents[].teams[].name
string
Yes
The team name.
agents[].labels
object[]
Yes
Assigned labels.
agents[].labels[].key
string
Yes
The label key.
agents[].labels[].value
string
Yes
The label value.
agents[].tools
object[]
Yes
agents[].tools[].name
string
Yes
The tool name.
agents[].tools[].description
string | null
Yes
The tool description, if any.
agents[].knowledgeSources
object[]
Yes
Assigned knowledge bases and connectors.
agents[].knowledgeSources[].name
string
Yes
The knowledge source name.
agents[].knowledgeSources[].description
string | null
Yes
The knowledge source description, if any.
agents[].knowledgeSources[].type
"knowledge_base" | "knowledge_connector"
Yes
Whether this source is a knowledge base or connector.
edit_agent
Required RBAC permission: agent:update
Input
Parameter
Type
Required
Description
id
string
Yes
The ID of the agent to edit. Use get_agent or list_agents to look it up by name.
subAgentIds
string[]
No
Agent IDs to add as delegation targets.
toolAssignments
object[]
No
Explicit tool assignments to add or update on the agent.
toolAssignments[].toolId
string
Yes
The ID of the tool to assign to the agent.
toolAssignments[].resolveAtCallTime
boolean
No
When true, resolve credentials and execution target at tool call time. Prefer this for builder flows.
toolAssignments[].credentialResolutionMode
"static" | "dynamic" | "enterprise_managed"
No
toolAssignments[].mcpServerId
string | null
No
Optional MCP server installation to pin the tool to when using static credential resolution.
description
string | null
No
New description for the agent.
icon
string | null
No
New emoji icon for the agent.
knowledgeBaseIds
string[]
No
Replace the agent's assigned knowledge bases with this set.
labels
object[]
No
Replace the agent's labels with this set.
labels[].key
string
Yes
labels[].value
string
Yes
name
string
No
New name for the agent.
connectorIds
string[]
No
Replace the agent's directly assigned knowledge connectors with this set.
scope
"personal" | "team" | "org"
No
Updated visibility scope for the agent.
toolExposureMode
"full" | "search_and_run_only"
No
How tools should be loaded for MCP clients and models.
accessAllTools
boolean
No
Allow dynamic tool access: search_tools/run_tool may discover and run any tool the calling user can access without assigning it to the agent. Enabling this forces toolExposureMode to 'search_and_run_only'.
accessAllSubagents
boolean
No
Allow dynamic subagent delegation: the agent may delegate to any internal agent the calling user can access, beyond explicitly-configured delegation targets (minus subagent exclusions).
suggestedPrompts
object[]
No
Replace the agent's suggested prompts.
suggestedPrompts[].summaryTitle
string
Yes
Short title shown to users for this suggested prompt.
suggestedPrompts[].prompt
string
Yes
Suggested prompt text users can click to start a conversation.
systemPrompt
string | null
No
New system prompt for the agent.
teams
string[]
No
Replace the teams attached to a team-scoped agent.
LLM Proxies
Tool
Description
Required RBAC Permission
create_llm_proxy
Create a new LLM proxy with the specified name and optional labels.
llmProxy:create
get_llm_proxy
Get a specific LLM proxy by ID or name.
llmProxy:read
edit_llm_proxy
Edit an existing LLM proxy.
llmProxy:update
create_llm_proxy
Required RBAC permission: llmProxy:create
Input
Parameter
Type
Required
Description
name
string
Yes
Name for the new resource.
scope
"personal" | "team" | "org"
No
Visibility scope. Defaults to personal for agents and org for LLM proxies/MCP gateways unless teams are provided.
labels
object[]
No
Optional key-value labels for organization and categorization.
labels[].key
string
Yes
labels[].value
string
Yes
teams
string[]
No
Team IDs to attach when creating a team-scoped resource.
toolExposureMode
"full" | "search_and_run_only"
No
How tools should be loaded for MCP clients and models. Use 'search_and_run_only' to keep the initial tool list small while letting search_tools find assigned tools and run_tool execute them. Assigned skill discovery/loading tools (list_skills, load_skill), sandbox runtime tools (run_command, download_file, upload_file) — when the code runtime is enabled and assigned — and persistent-files tools (search_files, read_file, save_file, edit_file, delete_file) — when the Projects feature is enabled and assigned — stay directly available in both modes. App tools (scaffold_app, edit_app, read_app, render_app, list_apps, and the rest of the app surface) are reached through search_tools/run_tool in 'search_and_run_only' mode.
accessAllTools
boolean
No
Allow dynamic tool access: search_tools/run_tool may discover and run any tool the calling user can access (MCP catalog tools and knowledge sources) without assigning it to the agent. Enabling this forces toolExposureMode to 'search_and_run_only', since dynamic access only works through the search/run dispatch surface. Defaults to false. Also gated by the organization's security settings.
accessAllSubagents
boolean
No
Allow dynamic subagent delegation: the agent may delegate to any internal agent the calling user can access, beyond explicitly-configured delegation targets (minus subagent exclusions). Defaults to false.
get_llm_proxy
Required RBAC permission: llmProxy:read
Input
Parameter
Type
Required
Description
id
string
No
The ID of the LLM proxy to fetch. Prefer the ID when you already have it.
name
string
No
The exact name of the LLM proxy to fetch when you do not already have the ID.
Output
Field
Type
Required
Description
id
string
Yes
The resource ID.
name
string
Yes
The resource name.
description
string | null
Yes
The resource description, if any.
icon
string | null
Yes
The emoji icon, if configured.
scope
"personal" | "team" | "org"
Yes
The visibility scope.
toolExposureMode
"full" | "search_and_run_only"
Yes
How tools are loaded for MCP clients and models.
accessAllTools
boolean
Yes
Whether search_tools/run_tool may dynamically access every tool the calling user can access.
accessAllSubagents
boolean
Yes
Whether the agent may delegate to every internal agent the calling user can access.
agentType
"agent" | "llm_proxy" | "mcp_gateway" | "profile"
Yes
The resource type.
systemPrompt
string | null
No
teams
object[]
Yes
The teams attached to it.
teams[].id
string
Yes
The team ID.
teams[].name
string
Yes
The team name.
labels
object[]
Yes
Assigned labels.
labels[].key
string
Yes
The label key.
labels[].value
string
Yes
The label value.
tools
object[]
Yes
Assigned tools.
tools[].id
string
Yes
The assigned tool ID.
tools[].name
string
Yes
The tool name.
tools[].description
string | null
Yes
The tool description, if any.
tools[].catalogId
string | null
Yes
The MCP catalog ID the tool comes from, if any.
knowledgeBaseIds
string[]
Yes
Assigned knowledge base IDs.
connectorIds
string[]
Yes
Assigned knowledge connector IDs.
suggestedPrompts
object[]
Yes
Configured suggested prompts.
suggestedPrompts[].summaryTitle
string
Yes
The short title shown in the chat UI.
suggestedPrompts[].prompt
string
Yes
The suggested prompt text.
edit_llm_proxy
Required RBAC permission: llmProxy:update
Input
Parameter
Type
Required
Description
id
string
Yes
The ID of the LLM proxy to edit. Use get_llm_proxy to look it up by name first if needed.
description
string | null
No
New description for the LLM proxy.
icon
string | null
No
New emoji icon for the LLM proxy.
labels
object[]
No
Replace the LLM proxy's labels with this set.
labels[].key
string
Yes
labels[].value
string
Yes
name
string
No
New name for the LLM proxy.
scope
"personal" | "team" | "org"
No
Updated visibility scope for the LLM proxy.
toolExposureMode
"full" | "search_and_run_only"
No
How tools should be loaded for MCP clients and models.
teams
string[]
No
Replace the teams attached to a team-scoped LLM proxy.
MCP Gateways
Tool
Description
Required RBAC Permission
create_mcp_gateway
Create a new MCP gateway with the specified name, optional labels, and optional assigned knowledge bases or knowledge connectors.
mcpGateway:create
get_mcp_gateway
Get a specific MCP gateway by ID or name.
mcpGateway:read
edit_mcp_gateway
Edit an existing MCP gateway.
mcpGateway:update
create_mcp_gateway
Required RBAC permission: mcpGateway:create
Input
Parameter
Type
Required
Description
name
string
Yes
Name for the new resource.
scope
"personal" | "team" | "org"
No
Visibility scope. Defaults to personal for agents and org for LLM proxies/MCP gateways unless teams are provided.
labels
object[]
No
Optional key-value labels for organization and categorization.
labels[].key
string
Yes
labels[].value
string
Yes
teams
string[]
No
Team IDs to attach when creating a team-scoped resource.
toolExposureMode
"full" | "search_and_run_only"
No
How tools should be loaded for MCP clients and models.
accessAllTools
boolean
No
Allow dynamic tool access: search_tools/run_tool may discover and run any tool the calling user can access (MCP catalog tools and knowledge sources) without assigning it to the agent. Enabling this forces toolExposureMode to 'search_and_run_only', since dynamic access only works through the search/run dispatch surface. Defaults to false. Also gated by the organization's security settings.
accessAllSubagents
boolean
No
Allow dynamic subagent delegation: the agent may delegate to any internal agent the calling user can access, beyond explicitly-configured delegation targets (minus subagent exclusions). Defaults to false.
knowledgeBaseIds
string[]
No
Knowledge base IDs to assign to the agent. Use get_knowledge_bases first when you need to look up IDs by name.
connectorIds
string[]
No
Knowledge connector IDs to assign directly to the agent. Use get_knowledge_connectors first when you need to look up IDs by name.
get_mcp_gateway
Required RBAC permission: mcpGateway:read
Input
Parameter
Type
Required
Description
id
string
No
The ID of the MCP gateway to fetch. Prefer the ID when you already have it.
name
string
No
The exact name of the MCP gateway to fetch when you do not already have the ID.
Output
Field
Type
Required
Description
id
string
Yes
The resource ID.
name
string
Yes
The resource name.
description
string | null
Yes
The resource description, if any.
icon
string | null
Yes
The emoji icon, if configured.
scope
"personal" | "team" | "org"
Yes
The visibility scope.
toolExposureMode
"full" | "search_and_run_only"
Yes
How tools are loaded for MCP clients and models.
accessAllTools
boolean
Yes
Whether search_tools/run_tool may dynamically access every tool the calling user can access.
accessAllSubagents
boolean
Yes
Whether the agent may delegate to every internal agent the calling user can access.
agentType
"agent" | "llm_proxy" | "mcp_gateway" | "profile"
Yes
The resource type.
systemPrompt
string | null
No
teams
object[]
Yes
The teams attached to it.
teams[].id
string
Yes
The team ID.
teams[].name
string
Yes
The team name.
labels
object[]
Yes
Assigned labels.
labels[].key
string
Yes
The label key.
labels[].value
string
Yes
The label value.
tools
object[]
Yes
Assigned tools.
tools[].id
string
Yes
The assigned tool ID.
tools[].name
string
Yes
The tool name.
tools[].description
string | null
Yes
The tool description, if any.
tools[].catalogId
string | null
Yes
The MCP catalog ID the tool comes from, if any.
knowledgeBaseIds
string[]
Yes
Assigned knowledge base IDs.
connectorIds
string[]
Yes
Assigned knowledge connector IDs.
suggestedPrompts
object[]
Yes
Configured suggested prompts.
suggestedPrompts[].summaryTitle
string
Yes
The short title shown in the chat UI.
suggestedPrompts[].prompt
string
Yes
The suggested prompt text.
edit_mcp_gateway
Required RBAC permission: mcpGateway:update
Input
Parameter
Type
Required
Description
id
string
Yes
The ID of the MCP gateway to edit. Use get_mcp_gateway to look it up by name first if needed.
description
string | null
No
New description for the MCP gateway.
icon
string | null
No
New emoji icon for the MCP gateway.
labels
object[]
No
Replace the MCP gateway's labels with this set.
labels[].key
string
Yes
labels[].value
string
Yes
name
string
No
New name for the MCP gateway.
scope
"personal" | "team" | "org"
No
Updated visibility scope for the MCP gateway.
toolExposureMode
"full" | "search_and_run_only"
No
How tools should be loaded for MCP clients and models.
teams
string[]
No
Replace the teams attached to a team-scoped MCP gateway.
knowledgeBaseIds
string[]
No
Replace the MCP gateway's assigned knowledge bases with this set.
connectorIds
string[]
No
Replace the MCP gateway's directly assigned knowledge connectors with this set.
MCP Servers
Tool
Description
Required RBAC Permission
search_private_mcp_registry
Search the private MCP registry for available MCP servers.
mcpRegistry:read
get_mcp_servers
List all MCP servers from the catalog.
mcpRegistry:read
get_mcp_server_tools
Get all tools available for a specific MCP server by its catalog ID (from get_mcp_servers).
mcpRegistry:read
edit_mcp_description
Edit an MCP server's display information and metadata.
mcpRegistry:update
edit_mcp_config
Edit an MCP server's technical configuration.
mcpRegistry:update
create_mcp_server
Create a new MCP server in the private registry.
mcpRegistry:create
deploy_mcp_server
Deploy (install) an MCP server from the catalog.
mcpRegistry:update
list_mcp_server_deployments
List all deployed (installed) MCP server instances accessible to the current user.
mcpRegistry:read
get_mcp_server_logs
Get recent container logs from a deployed local (K8s) MCP server.
mcpRegistry:read
reload_mcp_server_tools
Re-discover a deployed MCP server's tools from the live server and refresh Archestra's tool catalog for it — picks up added, removed, and changed tools (names, descriptions, and input schemas) with...
mcpRegistry:update
create_mcp_server_installation_request
Allows users from within the Archestra Platform chat UI to submit a request for an MCP server to be added to their Archestra Platform's internal MCP server registry.
mcpServerInstallationRequest:create
search_private_mcp_registry
Required RBAC permission: mcpRegistry:read
Input
Parameter
Type
Required
Description
query
string
No
Optional search query to filter MCP servers by name or description.
Output
Field
Type
Required
Description
items
object[]
Yes
Catalog items matching the search.
items[].id
string
Yes
The catalog item ID.
items[].name
string
Yes
The MCP server name.
items[].version
string | null
Yes
The version, if provided.
items[].description
string | null
Yes
The server description, if any.
items[].serverType
"local" | "remote" | "builtin" | "app"
Yes
Server type: local, remote, builtin, or app (user-generated App).
items[].serverUrl
string | null
Yes
The remote server URL, if applicable.
items[].repository
string | null
Yes
The repository URL, if available.
get_mcp_servers
Required RBAC permission: mcpRegistry:read
This tool takes no arguments.
Output
Field
Type
Required
Description
items
object[]
Yes
Available MCP servers.
items[].id
string
Yes
The catalog item ID.
items[].name
string
Yes
The MCP server name.
items[].icon
string | null
Yes
The emoji icon, if any.
items[].description
string | null
Yes
The server description, if any.
items[].scope
"personal" | "team" | "org"
No
The visibility scope of the server.
items[].teams
object[]
Yes
Teams attached to a team-scoped server.
items[].teams[].id
string
Yes
The team ID.
items[].teams[].name
string
Yes
The team name.
get_mcp_server_tools
Required RBAC permission: mcpRegistry:read
Input
Parameter
Type
Required
Description
mcpServerId
string
Yes
The catalog ID of the MCP server.
Output
Field
Type
Required
Description
tools
object[]
Yes
Tools exposed by the selected MCP server.
tools[].id
string
Yes
The tool ID.
tools[].name
string
Yes
The tool name.
tools[].description
string | null
No
The tool description, if any.
tools[].catalogId
string | null
No
The MCP catalog ID this tool belongs to.
edit_mcp_description
Required RBAC permission: mcpRegistry:update
Input
Parameter
Type
Required
Description
id
string
Yes
The catalog ID of the MCP server to edit. Use get_mcp_servers to look it up by name.
name
string
No
Display name for the MCP server.
description
string | null
No
Description of the MCP server.
icon
string | null
No
Emoji icon for the MCP server.
docsUrl
string | null
No
Documentation URL.
repository
string | null
No
Source code repository URL.
version
string | null
No
Version string.
instructions
string | null
No
Setup or usage instructions.
scope
"personal" | "team" | "org"
No
Visibility scope.
labels
object[]
No
Key-value labels for organization/categorization.
labels[].key
string
Yes
Label key.
labels[].value
string
Yes
Label value.
teams
string[]
No
Team IDs for team-scoped access control.
edit_mcp_config
Required RBAC permission: mcpRegistry:update
Input
Parameter
Type
Required
Description
id
string
Yes
The catalog ID of the MCP server to edit. Use get_mcp_servers to look it up by name.
serverType
"local" | "remote" | "builtin"
No
Server type: local, remote, or builtin.
serverUrl
string | null
No
[Remote] The URL of the remote MCP server.
requiresAuth
boolean
No
[Remote] Whether the server requires authentication.
authDescription
string | null
No
[Remote] How to set up authentication.
authFields
object[]
No
[Remote] Authentication field definitions.
authFields[].name
string
Yes
Auth field name.
authFields[].label
string
Yes
Human-readable auth field label.
authFields[].type
"header" | "query" | "cookie"
Yes
Where to send this auth field.
authFields[].secret
boolean
Yes
Whether this field contains secret data.
oauthConfig
object
No
[Remote] OAuth configuration for the server.
command
string
No
[Local] Command to run (for example npx, uvx, or node).
arguments
string[]
No
[Local] Command-line arguments.
environment
object[]
No
[Local] Environment variables for the server process.
environment[].key
string
Yes
Environment variable name.
environment[].type
"plain_text" | "secret" | "boolean" | "number"
Yes
Environment variable value type.
environment[].value
string
No
Literal environment variable value.
environment[].promptOnInstallation
boolean
Yes
Whether to prompt for this value during installation.
environment[].required
boolean
No
Whether the value is required.
environment[].description
string
No
Description shown to users.
environment[].default
any
No
Default value.
environment[].mounted
boolean
No
For secret values, mount as a file instead of an env var.
envFrom
object[]
No
[Local] Import env vars from Kubernetes Secrets or ConfigMaps.
envFrom[].type
"secret" | "configMap"
Yes
Import source type.
envFrom[].name
string
Yes
Secret or ConfigMap name.
envFrom[].prefix
string
No
Optional environment variable prefix.
dockerImage
string
No
[Local] Custom Docker image.
serviceAccount
string
No
[Local] Kubernetes ServiceAccount name.
transportType
"stdio" | "streamable-http"
No
[Local] Transport type.
httpPort
number
No
[Local] HTTP port for streamable-http transport.
httpPath
string
No
[Local] HTTP path for streamable-http transport.
nodePort
number
No
[Local] Kubernetes NodePort for local development.
imagePullSecrets
object[]
No
[Local] Image pull secrets for private registries.
Create a new team in the organization, optionally with key-value labels.
team:create
get_team
Retrieve a single team by its ID or name, including its current member count.
team:read †
list_teams
List all teams in the organization, optionally filtered by a name substring.
team:read †
edit_team
Update a team's name, description, and/or labels.
team:update
delete_team
Delete a team by ID.
team:delete
list_team_members
List all members of a team along with their roles.
team:read †
add_team_member
Add an organization user to a team by user ID or email, optionally as an admin.
team:read †
update_team_member_role
Change a team member's role between admin and member.
team:read †
remove_team_member
Remove a member from a team.
team:read †
list_team_external_groups
List the external identity provider groups mapped to a team for SSO team sync.
team:read
add_team_external_group
Map an external identity provider group to a team for SSO team sync: users whose SSO group memberships match are automatically added to or removed from the team on login.
team:read
remove_team_external_group
Remove an external group mapping from a team's SSO team sync, by mapping ID or by group identifier.
team:read
† This tool enforces an additional access requirement beyond its RBAC permission — see its details below.
create_team
Required RBAC permission: team:create
Input
Parameter
Type
Required
Description
name
string
Yes
The name of the team.
description
string
No
Optional human-readable description of the team.
labels
object[]
No
Optional key-value labels to assign to the team for organization and categorization (e.g. cost-center, environment).
labels[].key
string
Yes
labels[].value
string
Yes
Output
Field
Type
Required
Description
team
object
Yes
team.id
string
Yes
The team ID.
team.name
string
Yes
The team name.
team.description
string | null
Yes
The team description, if any.
team.organizationId
string
Yes
The organization the team belongs to.
team.createdBy
string | null
Yes
The ID of the user who created the team.
team.memberCount
number
Yes
The number of members currently in the team.
team.labels
object[]
Yes
Key-value labels assigned to the team.
team.labels[].key
string
Yes
The label key.
team.labels[].value
string
Yes
The label value.
team.createdAt
string
Yes
ISO timestamp when the team was created.
team.updatedAt
string
Yes
ISO timestamp when the team was last updated.
get_team
Required RBAC permission: team:read
Additional access requirement: Callers without organization-level team management (team:create) can only read teams they are a member of.
Input
Parameter
Type
Required
Description
id
string
No
The ID of the team to fetch.
name
string
No
The name of the team to fetch (within the organization).
Output
Field
Type
Required
Description
team
object
Yes
team.id
string
Yes
The team ID.
team.name
string
Yes
The team name.
team.description
string | null
Yes
The team description, if any.
team.organizationId
string
Yes
The organization the team belongs to.
team.createdBy
string | null
Yes
The ID of the user who created the team.
team.memberCount
number
Yes
The number of members currently in the team.
team.labels
object[]
Yes
Key-value labels assigned to the team.
team.labels[].key
string
Yes
The label key.
team.labels[].value
string
Yes
The label value.
team.createdAt
string
Yes
ISO timestamp when the team was created.
team.updatedAt
string
Yes
ISO timestamp when the team was last updated.
list_teams
Required RBAC permission: team:read
Additional access requirement: Callers without organization-level team management (team:create) only see teams they are a member of.
Input
Parameter
Type
Required
Description
name
string
No
Optional case-insensitive name substring to filter by.
Output
Field
Type
Required
Description
teams
object[]
Yes
teams[].id
string
Yes
The team ID.
teams[].name
string
Yes
The team name.
teams[].description
string | null
Yes
The team description, if any.
teams[].organizationId
string
Yes
The organization the team belongs to.
teams[].createdBy
string | null
Yes
The ID of the user who created the team.
teams[].memberCount
number
Yes
The number of members currently in the team.
teams[].labels
object[]
Yes
Key-value labels assigned to the team.
teams[].labels[].key
string
Yes
The label key.
teams[].labels[].value
string
Yes
The label value.
teams[].createdAt
string
Yes
ISO timestamp when the team was created.
teams[].updatedAt
string
Yes
ISO timestamp when the team was last updated.
edit_team
Required RBAC permission: team:update
Input
Parameter
Type
Required
Description
id
string
Yes
The ID of the team to update.
name
string
No
Optional new team name.
description
string | null
No
Optional new team description. Pass null to clear an existing description.
labels
object[]
No
Replace the team's labels with this set. Pass an empty array to remove all labels. Omit to leave labels unchanged.
labels[].key
string
Yes
labels[].value
string
Yes
Output
Field
Type
Required
Description
team
object
Yes
team.id
string
Yes
The team ID.
team.name
string
Yes
The team name.
team.description
string | null
Yes
The team description, if any.
team.organizationId
string
Yes
The organization the team belongs to.
team.createdBy
string | null
Yes
The ID of the user who created the team.
team.memberCount
number
Yes
The number of members currently in the team.
team.labels
object[]
Yes
Key-value labels assigned to the team.
team.labels[].key
string
Yes
The label key.
team.labels[].value
string
Yes
The label value.
team.createdAt
string
Yes
ISO timestamp when the team was created.
team.updatedAt
string
Yes
ISO timestamp when the team was last updated.
delete_team
Required RBAC permission: team:delete
Input
Parameter
Type
Required
Description
id
string
Yes
The ID of the team to delete.
Output
Field
Type
Required
Description
success
boolean
Yes
id
string
Yes
list_team_members
Required RBAC permission: team:read
Additional access requirement: Callers without organization-level team management (team:create) can only read members of teams they are a member of.
Input
Parameter
Type
Required
Description
team_id
string
Yes
The ID of the team whose members to list.
Output
Field
Type
Required
Description
members
object[]
Yes
members[].id
string
Yes
The team membership row ID.
members[].teamId
string
Yes
The team the membership belongs to.
members[].userId
string
Yes
The ID of the member user.
members[].role
"admin" | "member"
Yes
The member's role within the team (admin or member).
members[].syncedFromSso
boolean
Yes
Whether this membership is managed by SSO group sync.
members[].name
string | null
No
The member's display name, when available.
members[].email
string
No
The member's email, when available.
members[].createdAt
string
Yes
ISO timestamp when the membership was created.
add_team_member
Required RBAC permission: team:read
Additional access requirement: Beyond team:read, the caller must be an organization-level team manager (a role granting team:create) or an admin of the target team.
Input
Parameter
Type
Required
Description
team_id
string
Yes
The ID of the team to add the member to.
user
string
Yes
The user to add, identified by their user ID or email address. The user must already belong to the organization.
role
"admin" | "member"
No
The role to assign within the team. Defaults to 'member'.
Output
Field
Type
Required
Description
member
object
Yes
member.id
string
Yes
The team membership row ID.
member.teamId
string
Yes
The team the membership belongs to.
member.userId
string
Yes
The ID of the member user.
member.role
"admin" | "member"
Yes
The member's role within the team (admin or member).
member.syncedFromSso
boolean
Yes
Whether this membership is managed by SSO group sync.
member.name
string | null
No
The member's display name, when available.
member.email
string
No
The member's email, when available.
member.createdAt
string
Yes
ISO timestamp when the membership was created.
update_team_member_role
Required RBAC permission: team:read
Additional access requirement: Beyond team:read, the caller must be an organization-level team manager (a role granting team:create) or an admin of the target team.
Input
Parameter
Type
Required
Description
team_id
string
Yes
The ID of the team.
user_id
string
Yes
The ID of the member user to update.
role
"admin" | "member"
Yes
The new role for the member (admin or member).
Output
Field
Type
Required
Description
member
object
Yes
member.id
string
Yes
The team membership row ID.
member.teamId
string
Yes
The team the membership belongs to.
member.userId
string
Yes
The ID of the member user.
member.role
"admin" | "member"
Yes
The member's role within the team (admin or member).
member.syncedFromSso
boolean
Yes
Whether this membership is managed by SSO group sync.
member.name
string | null
No
The member's display name, when available.
member.email
string
No
The member's email, when available.
member.createdAt
string
Yes
ISO timestamp when the membership was created.
remove_team_member
Required RBAC permission: team:read
Additional access requirement: Beyond team:read, the caller must be an organization-level team manager (a role granting team:create) or an admin of the target team.
Input
Parameter
Type
Required
Description
team_id
string
Yes
The ID of the team.
user_id
string
Yes
The ID of the member user to remove from the team.
Output
Field
Type
Required
Description
success
boolean
Yes
teamId
string
Yes
userId
string
Yes
list_team_external_groups
Required RBAC permission: team:read
Input
Parameter
Type
Required
Description
team_id
string
Yes
The ID of the team whose external group mappings to list.
Output
Field
Type
Required
Description
externalGroups
object[]
Yes
externalGroups[].id
string
Yes
The external group mapping ID.
externalGroups[].teamId
string
Yes
The team the mapping belongs to.
externalGroups[].groupIdentifier
string
Yes
The external identity provider group identifier.
externalGroups[].createdAt
string
Yes
ISO timestamp when the mapping was created.
add_team_external_group
Required RBAC permission: team:read
Input
Parameter
Type
Required
Description
team_id
string
Yes
The ID of the team to map the external group to.
group_identifier
string
Yes
The external identity provider group identifier. Format varies by provider: LDAP Distinguished Name (e.g. cn=admins,ou=groups,dc=example,dc=com), OAuth/OIDC group name from the groups claim, SAML group attribute value, or Azure AD group object ID (GUID). Matched case-insensitively.
Output
Field
Type
Required
Description
externalGroup
object
Yes
externalGroup.id
string
Yes
The external group mapping ID.
externalGroup.teamId
string
Yes
The team the mapping belongs to.
externalGroup.groupIdentifier
string
Yes
The external identity provider group identifier.
externalGroup.createdAt
string
Yes
ISO timestamp when the mapping was created.
remove_team_external_group
Required RBAC permission: team:read
Input
Parameter
Type
Required
Description
team_id
string
Yes
The ID of the team.
group_id
string
No
The ID of the external group mapping to remove.
group_identifier
string
No
The external group identifier to remove, as an alternative to group_id. Matched case-insensitively.
Output
Field
Type
Required
Description
success
boolean
Yes
teamId
string
Yes
Limits
Tool
Description
Required RBAC Permission
create_limit
Create a new cost or usage limit for an organization, team, agent, user, virtual key, environment, or MCP gateway.
llmLimit:create
get_limits
Retrieve all limits, optionally filtered by entity type and/or entity ID.
llmLimit:read
update_limit
Update mutable fields on an existing limit.
llmLimit:update
delete_limit
Delete an existing limit by ID.
llmLimit:delete
get_agent_token_usage
Get the total token usage (input and output) for a specific agent.
llmLimit:read
get_llm_proxy_token_usage
Get the total token usage (input and output) for a specific LLM proxy.
Change who can see a project: the whole organization ("organization"), specific teams ("team"), or only the owner ("none").
project:update †
† This tool enforces an additional access requirement beyond its RBAC permission — see its details below.
todo_write
Required RBAC permission: None (no additional RBAC permission required)
Input
Parameter
Type
Required
Description
todos
object[]
Yes
Array of todo items to write to the conversation.
todos[].id
integer
Yes
Unique identifier for the todo item.
todos[].content
string
Yes
The content or description of the todo item.
todos[].status
"pending" | "in_progress" | "completed"
Yes
The current status of the todo item.
Output
Field
Type
Required
Description
success
boolean
Yes
Whether the write succeeded.
todoCount
integer
Yes
How many todo items were written.
create_project_from_conversation
Required RBAC permission: project:create
Input
Parameter
Type
Required
Description
name
string
No
Project name. Defaults to the chat's title when omitted.
description
string
No
Optional project description.
Output
Field
Type
Required
Description
success
boolean
Yes
Whether the project was created.
project_id
string
Yes
The new project's id.
project_name
string
Yes
The new project's name.
project_slug
string
Yes
The new project's slug.
files_transferred
integer
Yes
How many of the chat's files were moved into the project.
set_project_share
Required RBAC permission: project:update
Additional access requirement: Beyond project:update, the caller must own the project (or hold project:admin), and moving a project into or out of organization-wide visibility additionally requires project:share-org.
Input
Parameter
Type
Required
Description
visibility
"organization" | "team" | "none"
Yes
Who can see the project: "organization" for everyone in the organization, "team" for the given teams, "none" to make it owner-only.
team_ids
string[]
No
Ids of the teams to share with. Required when visibility is "team"; ignored otherwise.
project_id
string
No
Project to change. Defaults to the current chat's project.
Output
Field
Type
Required
Description
success
boolean
Yes
Whether the sharing was updated.
project_id
string
Yes
The affected project's id.
project_name
string
Yes
The affected project's name.
visibility
"organization" | "team" | "none"
Yes
The project's sharing after the update.
Meta
Tool
Description
Required RBAC Permission
search_tools
Search the tools available to this agent and to you on demand.
None (no additional RBAC permission required)
run_tool
Dispatch to any tool available to this agent, including built-in platform tools, agent delegation tools ('agent-'), or third-party MCP tools exposed through the MCP Gateway (e.g.
None (no additional RBAC permission required)
search_tools
Required RBAC permission: None (no additional RBAC permission required)
Input
Parameter
Type
Required
Description
query
string
Yes
Keywords for the capability you need — combine the action (verb + object) with the server/product name when you know it, e.g. 'github search repositories' or 'slack send message'. Avoid querying with a bare product/server name on its own. Results are keyword-ranked across tool names, descriptions, and argument names/descriptions. If nothing fits, reformulate with different keywords and search again rather than settling for a poor match.
limit
integer
No
Maximum number of matching tools to return.
mode
"keyword" | "regex"
No
Search mode. 'keyword' (default) keyword-ranks the query across tool fields. 'regex' treats query as a case-insensitive regular expression matched against tool names, titles, and descriptions — use it when you know a naming pattern, e.g. '^github__' or 'search|find'.
Output
Field
Type
Required
Description
total
integer
Yes
Number of returned tools.
matchCount
integer
Yes
Total tools matching the query before the limit was applied (>= total).
truncated
boolean
Yes
True when matchCount exceeds the returned tools (results cut by limit).
hint
string | null
Yes
Actionable guidance when results were truncated or empty (an empty result also names which query terms matched no tool text).
tools
object[]
Yes
tools[].toolName
string
Yes
Exact tool name to pass to run_tool.
tools[].description
string | null
Yes
Short tool description, if available.
tools[].source
"archestra" | "mcp" | "agent_delegation"
Yes
Where the tool comes from.
tools[].server
string | null
Yes
MCP server prefix for third-party MCP tools when available.
tools[].available
boolean
Yes
False when the tool's MCP connection is not installed; it stays discoverable but cannot run until reconnected.
tools[].unavailableReason
string | null
Yes
Compact reason and recovery action when available is false; null otherwise.
tools[].params
string
Yes
Compact one-line input signature — a summary, not the full schema. Parameters are joined by '; ', each rendered as name<!|?>:<type> where ! marks required and ? optional. Object parameters are expanded up to two levels as {child<!|?>:type{grandchild<!|?>:type}, …}, enums as enum(<json-values>), and a trailing — description is added when available. A trailing … on a type marks an object whose content is not fully shown (freeform or more deeply nested) — consult the task instructions or the full schema for its shape. Empty string when the tool takes no input. Pass matching values inside tool_args when calling run_tool; if a call is rejected as invalid, the error describes the expected input (for third-party tools, the full input schema).
run_tool
Required RBAC permission: None (no additional RBAC permission required)
Input
Parameter
Type
Required
Description
tool_name
string
Yes
Name of the tool to invoke. Use the exact name as it appears in the tools list, e.g. 'archestra__whoami', 'context7__resolve-library-id', or an agent delegation name 'agent-'.
tool_args
object
No
Arguments object for the target tool; must match its input schema.
Skills
Tool
Description
Required RBAC Permission
list_skills
List the Agent Skills available in this organization — one line per skill (name and description).
skill:read
load_skill
Load a specialized Agent Skill — a reusable SKILL.md instruction set.
skill:read
create_skill
Create a new Agent Skill from a SKILL.md manifest.
skill:create
update_skill
Update an existing Agent Skill from a SKILL.md manifest.
skill:update
edit_skill
Make a targeted edit to an existing Agent Skill without resending the whole SKILL.md.
skill:update
list_skills
Required RBAC permission: skill:read
This tool takes no arguments.
load_skill
Required RBAC permission: skill:read
Input
Parameter
Type
Required
Description
name
string
Yes
The skill to load, as named by list_skills.
path
string
No
Optional. Omit (or pass an empty string) to load the skill's instructions and bundled-file list. Pass a resource path from that list (e.g. references/REFERENCE.md) to read one bundled file instead.
create_skill
Required RBAC permission: skill:create
Input
Parameter
Type
Required
Description
content
string
Yes
A complete SKILL.md manifest: a YAML frontmatter block with name and description (and optional license, compatibility, allowed-tools, agent, templated, metadata), followed by the Markdown instruction body. Set templated: true to render the body through Handlebars (e.g. {{user.name}}) at activation. allowed-tools is a space-separated list of tools the skill is pre-approved to use. agent names an agent the skill runs in — when set, activating the skill delegates it to that agent instead of loading the instructions into the caller's context.
files
object[]
No
Optional bundled resource files. Each is { path, content } with text content; the path prefix classifies the file — references/ for docs, scripts/ for code, assets/ for other files.
files[].path
string
Yes
Resource path, e.g. references/API.md or scripts/run.py
files[].content
string
Yes
Text content of the file
files[].encoding
"utf8" | "base64"
No
update_skill
Required RBAC permission: skill:update
Input
Parameter
Type
Required
Description
name
string
Yes
The current name of the skill to update, as named by list_skills.
content
string
Yes
A complete SKILL.md manifest: a YAML frontmatter block with name and description (and optional license, compatibility, allowed-tools, agent, templated, metadata), followed by the Markdown instruction body. Set templated: true to render the body through Handlebars (e.g. {{user.name}}) at activation. allowed-tools is a space-separated list of tools the skill is pre-approved to use. agent names an agent the skill runs in — when set, activating the skill delegates it to that agent instead of loading the instructions into the caller's context.
files
object[]
No
Optional. WHEN PROVIDED, REPLACES THE SKILL'S ENTIRE bundled file set. Omit it to leave the existing resource files untouched. There is no per-file patch: to change one file you must resend all of them — read the current files back first with load_skill (with and without a path).
files[].path
string
Yes
Resource path, e.g. references/API.md or scripts/run.py
files[].content
string
Yes
Text content of the file
files[].encoding
"utf8" | "base64"
No
edit_skill
Required RBAC permission: skill:update
Input
Parameter
Type
Required
Description
name
string
Yes
The current name of the skill to edit, as named by list_skills.
baseVersion
integer
Yes
The version the edit is based on — the version shown on the <skill_content>/<skill_file> frame you loaded with load_skill. The edit is rejected if the skill's head has moved past it.
path
string
No
Omit (or pass an empty string) to edit the SKILL.md body; pass a bundled file path (from the <skill_resources> list) to edit that file instead. Only text (utf8) files are editable — binary assets are not.
edits
object[]
No
str_replace edits applied in order to the target; the whole edit is atomic (any failure leaves the skill unchanged). This is the way to change a large SKILL.md without resending it all. Pass either edits or replacementContent, never both.
edits[].old_str
string
Yes
Exact text to replace; must occur exactly once in the target (add surrounding context to disambiguate).
edits[].new_str
string
Yes
Replacement text (may be empty to delete).
replacementContent
string
No
The complete new content of the target, replacing it outright with no old_str matching — use it for a small file or a full rewrite. Prefer edits for the SKILL.md body so you don't resend the whole thing. Pass either edits or replacementContent, never both.
Apps
Tool
Description
Required RBAC Permission
scaffold_app
Create a new interactive app (dashboard, form, tracker, game, or any custom UI) seeded from the default starter template.
app:create
refine_app
Clarify what an existing app should be and record it as a persisted product spec, between scaffold_app and edit_app.
app:update
list_apps
List apps visible to the caller, optionally filtered by name or labels — use it to find an app's id.
app:read
render_app
Render an existing app by id, if the caller may view it.
app:read
read_app
Return an app's stored HTML (pre-injection — exactly what was saved, without the platform SDK or base stylesheet) plus its version, byte size, name, and scope.
app:read
edit_app
The single path for any change to an app's HTML: pass edits for targeted str_replace changes, replacementHtml to swap in a complete new document (no old_str matching), or replacementHtmlSource to s...
app:update
set_app_tools
Replace an existing app's assigned upstream tools with exactly the set you pass (the full desired list; [] clears all).
app:update
set_app_labels
Replace an app's labels with exactly the set you pass ([] clears them).
app:update
validate_app
The pre-publish gate for an app's head version: static structural checks (findings, each carrying its own specific message) plus the most recent live-render diagnostics (live), with ok true w...
app:read
publish_app
Share an app with others: promote it out of personal scope so others can run it — this is how you distribute or make an app available to a team or the whole org — to specific teams (scope: team, wi...
app:update
preview_app_tool
Run one of an app's assigned MCP tools server-side, exactly as the rendered app would (as you, the viewing user, with your MCP credentials), and return its real output.
app:update
get_app_diagnostics
Check how the app's current version rendered for you.
app:read
delete_app
Soft-delete an app the caller owns or administers, and remove its MCP backing so it is no longer served.
app:delete
app_data_get
Read a value from the calling app's data store (per-user or shared partition).
app:read
app_data_set
Write a value to the calling app's data store (per-user or shared partition).
app:update
app_data_list
List all entries in one partition of the calling app's data store.
app:read
app_data_delete
Delete a key from the calling app's data store (per-user or shared partition).
app:update
llm_complete
Run a single LLM completion for the calling app (backs archestra.llm.complete).
app:read
scaffold_app
Required RBAC permission: app:create
Input
Parameter
Type
Required
Description
name
string
Yes
App name.
description
string
No
Optional description.
scope
"personal" | "team" | "org"
No
Visibility scope, personal (default, owned by the calling user) or org. Team scope is not available here — team-scoped apps must be created in the Apps UI so teams can be assigned.
Optional key-value labels for organization and categorization.
labels[].key
string
Yes
labels[].value
string
Yes
tools
string[]
No
Upstream MCP tool names to assign to the new app (e.g. from search_tools), callable from its HTML via archestra.tools.call with the viewing user's credentials. Omitted leaves the app with no assigned tools.
Output
Field
Type
Required
Description
id
string
Yes
name
string
Yes
description
string | null
Yes
scope
"personal" | "team" | "org"
Yes
latestVersion
number
Yes
labels
object[]
Yes
Key-value labels for organization/categorization.
labels[].key
string
Yes
The label key.
labels[].value
string
Yes
The label value.
warnings
string[]
No
Soft save-time validation warnings about the html (the save succeeded); fix them via edit_app.
tools
string[]
No
The app's assigned tool names after this call (present when the tools param was given).
status
"ok" | "partial"
No
Absent or "ok" on full success. "partial" means the app was created (see id) but assigning its tools failed — the app exists; assign them with set_app_tools rather than re-scaffolding.
refine_app
Required RBAC permission: app:update
Input
Parameter
Type
Required
Description
appId
string
Yes
The app id to refine.
questions
object[]
No
Up to 3 clarifying questions to ask the user before consolidating the spec.
questions[].id
string
Yes
Stable key the answer is returned under.
questions[].prompt
string
Yes
The question shown to the user.
questions[].options
string[]
No
When present, the question is single-select over these plain-string option labels, e.g. ["Light", "Dark"] — never {label, value} objects; otherwise it is free-text.
spec
object
No
The consolidated product requirements to persist on the app (features/data/ui/tools — no implementation stack).
spec.summary
string
Yes
One-line summary of what the app is for.
spec.features
string[]
Yes
Concrete capabilities the app should provide.
spec.data
string | null
No
What the app reads/persists via the App Data Store — a free-form prose string, not a structured object.
spec.ui
string | null
No
UI / style direction as a free-form prose string, not a structured object.
spec.tools
string[]
Yes
Full names of the MCP tools the app calls through window.archestra.
Output
Field
Type
Required
Description
id
string
Yes
spec
object
Yes
The persisted spec when one was given, else the base spec seeded for the model.
spec.summary
string
Yes
One-line summary of what the app is for.
spec.features
string[]
Yes
Concrete capabilities the app should provide.
spec.data
string | null
No
What the app reads/persists via the App Data Store — a free-form prose string, not a structured object.
spec.ui
string | null
No
UI / style direction as a free-form prose string, not a structured object.
spec.tools
string[]
Yes
Full names of the MCP tools the app calls through window.archestra.
capability
object
Yes
capability.tools
object[]
Yes
capability.tools[].name
string
Yes
capability.tools[].description
string
Yes
capability.sdkSummary
string
Yes
answers
object
No
The user's answers to the clarifying questions, if any.
persisted
boolean
Yes
Whether a spec was persisted on the app head by this call.
list_apps
Required RBAC permission: app:read
Input
Parameter
Type
Required
Description
name
string
No
Filter by name. Each whitespace-separated word must appear in the name or description, in any order — so a remembered name matches even when its word order or punctuation differs from how the app was saved.
labels
object[]
No
Filter by labels. AND across keys, OR within the values given for the same key.
labels[].key
string
Yes
labels[].value
string
Yes
limit
integer
No
Output
Field
Type
Required
Description
apps
object[]
Yes
apps[].id
string
Yes
apps[].name
string
Yes
apps[].description
string | null
Yes
apps[].scope
"personal" | "team" | "org"
Yes
apps[].latestVersion
number
Yes
apps[].labels
object[]
Yes
Key-value labels for organization/categorization.
apps[].labels[].key
string
Yes
The label key.
apps[].labels[].value
string
Yes
The label value.
apps[].warnings
string[]
No
Soft save-time validation warnings about the html (the save succeeded); fix them via edit_app.
render_app
Required RBAC permission: app:read
Input
Parameter
Type
Required
Description
appId
string
Yes
The app id.
Output
Field
Type
Required
Description
id
string
Yes
name
string
Yes
description
string | null
Yes
scope
"personal" | "team" | "org"
Yes
latestVersion
number
Yes
labels
object[]
Yes
Key-value labels for organization/categorization.
labels[].key
string
Yes
The label key.
labels[].value
string
Yes
The label value.
warnings
string[]
No
Soft save-time validation warnings about the html (the save succeeded); fix them via edit_app.
read_app
Required RBAC permission: app:read
Input
Parameter
Type
Required
Description
appId
string
Yes
The app id.
version
integer
No
Specific version to read; defaults to the current head.
offset
integer
No
Start of the read window as a 0-based character offset (a JavaScript string index / UTF-16 code unit) into the stored HTML — character-based, not line-based, since minified HTML can be one enormous line. Defaults to 0. An offset past the end returns an empty window, not an error. A window never splits a character in half: its edges shift by one unit when they would.
limit
integer
No
Maximum number of characters to return, starting at offset. Omitted reads to the end of the document; 0 returns no content, just the size metadata.
Output
Field
Type
Required
Description
id
string
Yes
name
string
Yes
scope
"personal" | "team" | "org"
Yes
version
number
Yes
byteSize
number
Yes
UTF-8 byte size of the full stored HTML (never the window's).
totalChars
number
Yes
Total character length of the full stored HTML.
offset
number
Yes
Effective 0-based character offset of the returned window (0 for a full read; clamped to the end when past it).
hasMore
boolean
Yes
True when the document continues past the returned window.
html
string
Yes
The stored HTML, pre-injection (no SDK/base CSS) — the requested character window when offset/limit was passed.
edit_app
Required RBAC permission: app:update
Input
Parameter
Type
Required
Description
appId
string
Yes
The app id.
baseVersion
integer
No
Optional optimistic-concurrency guard: the version (from read_app) the edits are based on. Defaults to the current head, so a single editor never has to echo it back. When supplied, the edit is rejected if the app's head has moved past it.
edits
object[]
No
str_replace edits applied in order to the current HTML; the whole edit is atomic (any failure leaves the app unchanged). Pass exactly one of edits, replacementHtml, or replacementHtmlSource.
edits[].old_str
string
Yes
Exact text to replace; must occur exactly once in the current HTML (add surrounding context to disambiguate).
edits[].new_str
string
Yes
Replacement text (may be empty to delete).
replacementHtml
string
No
The complete new document, replacing the current HTML outright with no old_str matching — use this for a full rewrite instead of reproducing the whole document as an edit. Pass exactly one of edits, replacementHtml, or replacementHtmlSource.
replacementHtmlSource
object
No
Like replacementHtml, but the document is read server-side from a file you already saved instead of being written out here — use this when the HTML already exists as a file (assembled in the sandbox, or attached to the chat) so its bytes never have to be reproduced as tool arguments. The file must be UTF-8 text and is subject to the same size limit as any other document. Reads whatever the file holds at call time. Pass exactly one of edits, replacementHtml, or replacementHtmlSource.
replacementHtmlSource.fileId
string
Yes
Id of a saved file whose bytes become the document, as returned by download_file, save_file, or search_files.
Output
Field
Type
Required
Description
id
string
Yes
name
string
Yes
description
string | null
Yes
scope
"personal" | "team" | "org"
Yes
latestVersion
number
Yes
labels
object[]
Yes
Key-value labels for organization/categorization.
labels[].key
string
Yes
The label key.
labels[].value
string
Yes
The label value.
warnings
string[]
No
Soft save-time validation warnings about the html (the save succeeded); fix them via edit_app.
set_app_tools
Required RBAC permission: app:update
Input
Parameter
Type
Required
Description
appId
string
Yes
The app id whose tools to set.
tools
string[]
Yes
Upstream MCP tool names (e.g. from search_tools) to assign to the app, replacing its current set exactly — pass the full desired list, or [] to clear all.
Output
Field
Type
Required
Description
id
string
Yes
tools
string[]
Yes
The app's assigned tool names after this call.
set_app_labels
Required RBAC permission: app:update
Input
Parameter
Type
Required
Description
appId
string
Yes
The app id whose labels to set.
labels
object[]
Yes
Key-value labels to assign to the app, replacing its current set exactly — pass the full desired list, or [] to clear all. One value per key; a repeated key keeps the last one.
labels[].key
string
Yes
labels[].value
string
Yes
Output
Field
Type
Required
Description
id
string
Yes
labels
object[]
Yes
The app's labels after this call.
labels[].key
string
Yes
The label key.
labels[].value
string
Yes
The label value.
validate_app
Required RBAC permission: app:read
Input
Parameter
Type
Required
Description
appId
string
Yes
The app id to validate.
Output
Field
Type
Required
Description
id
string
Yes
version
number
Yes
The head version that was validated.
ok
boolean
Yes
True when there are no error-severity findings.
findings
object[]
Yes
findings[].severity
"error" | "warning"
Yes
findings[].message
string
Yes
live
object
Yes
Diagnostics from the most recent live render of the head version (untrusted iframe output). status no_render_observed means no render of this version has happened yet — live diagnostics are captured only when the app renders for a viewer, so this is the normal state right after authoring and a clean static pass (ok: true) is enough to proceed.
live.status
"no_render_observed" | "clean" | "errors"
Yes
live.version
number
Yes
live.entries
object[]
Yes
live.entries[].type
string
Yes
live.entries[].message
string
Yes
live.renderedAt
string | null
Yes
publish_app
Required RBAC permission: app:update
Input
Parameter
Type
Required
Description
appId
string
Yes
The app id to publish.
scope
"team" | "org"
Yes
Publish to specific teams or to the whole organization. Promotes the app out of personal scope.
teams
string[]
No
Target teams, each a team name or team id — required when scope is team. Pass the team name the user gave (e.g. ["Platform"]); no need to look up ids first.
Output
Field
Type
Required
Description
id
string
Yes
scope
"personal" | "team" | "org"
Yes
runUrl
string
Yes
Standalone page for the published app.
preview_app_tool
Required RBAC permission: app:update
Input
Parameter
Type
Required
Description
appId
string
Yes
The app id whose assigned tool to run.
toolName
string
Yes
Name of an MCP tool assigned to the app (exactly as archestra.tools.call would receive it).
args
object
No
Arguments to pass to the tool (defaults to {}).
Output
Field
Type
Required
Description
toolName
string
Yes
isError
boolean
Yes
truncated
boolean
Yes
output
string
Yes
The JSON-serialized value archestra.tools.call resolves with for this result, framed as untrusted data (media dataUrls are elided).
get_app_diagnostics
Required RBAC permission: app:read
Input
Parameter
Type
Required
Description
appId
string
Yes
The app id.
Output
Field
Type
Required
Description
status
"no_render_observed" | "clean" | "errors"
Yes
version
number | null
Yes
The rendered version, or the current head when none observed.
entries
object[]
Yes
entries[].type
string
Yes
entries[].message
string
Yes
renderedAt
string | null
Yes
screenshot
boolean
Yes
Whether a screenshot of the render is attached as an image to this result.
delete_app
Required RBAC permission: app:delete
Input
Parameter
Type
Required
Description
appId
string
Yes
The app id.
app_data_get
Required RBAC permission: app:read
Input
Parameter
Type
Required
Description
key
string
Yes
The data store key.
scope
"user" | "app"
No
Storage partition: "user" (default) is private to the viewing user, "app" is shared by everyone using the app.
Output
Field
Type
Required
Description
value
any
Yes
revision
integer | null
Yes
owner
string | null
Yes
User id owning a shared key, or null if collaborative.
app_data_set
Required RBAC permission: app:update
Input
Parameter
Type
Required
Description
key
string
Yes
The data store key.
value
any
Yes
Any JSON-serializable value except null (use app_data_delete to clear a key). Pass objects/arrays directly — get returns exactly what was stored, no JSON.stringify needed.
scope
"user" | "app"
No
Storage partition: "user" (default) is private to the viewing user, "app" is shared by everyone using the app.
expectedRevision
integer
No
Optimistic concurrency guard. Omit for last-writer-wins. 0 = create only if the key is absent. A positive value = overwrite only if the key is still at that revision (from a prior get/set); otherwise the write is rejected as a conflict.
claimOwner
boolean
No
Shared-scope only: when creating a NEW key, claim it so only you (or an app admin/author) may later overwrite or delete it. Has no effect on the "user" scope or on an existing key.
Output
Field
Type
Required
Description
key
string
Yes
revision
integer
Yes
owner
string | null
Yes
User id owning a shared key, or null if collaborative.
app_data_list
Required RBAC permission: app:read
Input
Parameter
Type
Required
Description
scope
"user" | "app"
No
Storage partition: "user" (default) is private to the viewing user, "app" is shared by everyone using the app.
Output
Field
Type
Required
Description
entries
object[]
Yes
entries[].key
string
Yes
entries[].value
any
Yes
entries[].revision
integer
Yes
entries[].owner
string | null
Yes
User id owning a shared key, or null if collaborative.
app_data_delete
Required RBAC permission: app:update
Input
Parameter
Type
Required
Description
key
string
Yes
The data store key.
scope
"user" | "app"
No
Storage partition: "user" (default) is private to the viewing user, "app" is shared by everyone using the app.
llm_complete
Required RBAC permission: app:read
Input
Parameter
Type
Required
Description
prompt
string
Yes
The prompt to complete.
system
string
No
Optional system instruction that frames the completion.
jsonMode
boolean
No
When true, steer the model to return a single valid JSON value (the caller still parses the returned string).
