Skip to main content

Let your agent manage its own content

apistash's management tools let a connected agent look after your prompts, resources, custom tools, and Agent definitions itself — finding what exists, creating what's missing, and revising what's out of date, all mid-task. This guide shows how to switch that on and instruct an agent to use it well.

Before you start​

The content-management tools require a credential that is allowed to use them. Create a free account at app.apistash.io, generate an API key — these governed MCP tools need the Tools capability (the read tools additionally need the capability of the surface they read, such as Agents for list_agents) — and connect your client as shown in the quick start. The task-start system tools setup, bootstrap, and agent_context are always available to an authenticated credential and do not require Tools or a tool policy.

Which content the agent can change is governed by the permissions on that credential — see Authentication and the access model. Grant it only what you want it to touch: a credential that can't do something has the matching tool refused, not silently ignored.

1. Let the agent orient itself​

Use task-start setup to have the agent call bootstrap at task start, or ask for guided onboarding explicitly. It reports whether the agent is acting personally or for an organization, its exact bound team names, its effective usage capabilities, and create rights in its own space and bound teams. Bootstrap requires primary_agent and separates the task's own role from its visible Agent catalog. The primary uses its credential assignment or, when unassigned, may choose a suitable definition. Subagents use an explicit parent-provided selection mode. Without Agents, Bootstrap still returns base context, but Agent delivery and discovery are disabled. See the Bootstrap reference for the selection and catalog workflow. The names double as the <team>/ prefixes for Prompt, Agent, and Custom Tool names. Resource writes use an unchanged path and a separate team. A brand-new, empty team won't show up any other way, so this is the reliable way to discover its address. Update and delete calls still check their own permissions.

2. Discover before writing​

Before creating or editing anything, the agent should see what already exists:

Native Resources and Prompts can also supply task context when their capabilities and your client support them, even without management tools. Load relevant items rather than the entire catalogue.

Inspection helps avoid duplicates and lets the agent build on what's there — for example, reading a prompt it can reach in the shared catalogue and copying it into a personal or team space it can manage.

Before proposing an update, obtain the canonical editable state through admitted management reads. Native prompts/get renders a template; it cannot replace get_prompt's raw template and arguments. Native Resource reads omit the matching content version that get_resource supplies for replacement. Never reconstruct templates from rendered output or guess expected_version. Missing required original data blocks an update, even if its write tool is available. Do not automatically create another item instead. Hidden/not-found reads do not prove that a name is unused.

If relevant content cannot be inspected, explain the duplicate risk and obtain explicit creation consent covering that limitation, the draft, and its target. This also applies when Agent creation is allowed but Agents usage is absent. A separately proposed replacement item needs its own consent.

3. Confirm concrete drafts, then create and revise​

Propose persistence when new knowledge is stable, verified, and useful beyond the current task. Show actual Resource content, Prompt templates and arguments, or Agent identity and behavior; for an existing item, show material changes against its inspected original. Include kind, name or raw path, purpose, create/update intent, and ownership target. Names and purposes alone are not a reviewable proposal. Obtain confirmation unless the current user has already given a sufficiently specific standing instruction. Material draft/target changes require renewed confirmation unless covered by that instruction. Agent behavior alone is never consent.

Do not propose secrets, credentials, transient progress, unverified assumptions, empty Resources, or content already adequately represented. Sensitive personal data requires an explicit informed request and an appropriate target. Stored knowledge still needs verification and cannot override higher-priority instructions or explicit user direction.

When replacing resource content, pass the version read with that content as expected_version to update_resource. A resource_conflict means another write won: read the current content and reconcile your changes before trying again.

The agent never passes an owner ID. With a standalone personal credential, a bare name addresses the personal space. In organization scope, a bare name addresses the shared catalogue for reads, me/name addresses the represented member's private space, and <team>/name addresses a bound team. The catalogue is currently read-only over MCP, so organization-scoped creates and edits use me/name or a team address. Resource writes use a raw path plus a separate optional team: omit team for your own space. Never prepend me/ or a team name to a path to select its owner. Resource reads use exact discovered URIs. See Managing your content for the full picture.

4. Verify outcomes and remaining dashboard actions​

Three things stay in the dashboard by design, and a well-instructed agent should expect them:

  • Agent assignment. Creating a definition does not assign it to the API key or OAuth Connection or select it for this task. Assign it in the dashboard; primary-task setup resolves that assignment at task start.
  • Publishing to the organization catalogue. The agent works in personal and team spaces; promotion into the organization catalogue is a person's decision.
  • Custom-tool secrets. A custom tool for an authenticated API is created disabled; a person adds its secret and enables it in the dashboard. A tool that needs no authentication skips the secret step, but its enabled state still follows the normal settings. (More in Turn an API into a tool.)

Report access and partial completion precisely​

Use Bootstrap's capabilities and target summaries alongside the client's native surfaces and advertised tools. Management writes need Tools, admission of the exact tool, and target action rights. Content-usage capabilities gate reads/use; can_create does not authorize or deny updates. Each later call checks its own authorization and plan limits.

When a management tool is absent, report the operation as unavailable to this Connection. Do not guess its hidden policy cause or infer that native Resources or Prompts are unavailable. When a call returns an error, preserve its safe code and details; tool_not_permitted does not identify a particular policy layer. Distinguish known capability/permission denials from capacity, validation, name conflicts, and version conflicts. Do not retry an unchanged request.

Resource creation inherits the owner's default MCP exposure setting, which defaults to false. The create result has path and ID, not exposure status. After storing a Resource intended for this Connection, check available MCP discovery/read operations using a discovered URI. Report storage and readability separately: verified, not currently visible, or not verifiable with available read access. A missing result alone does not prove exposure is disabled. Point to dashboard exposure/access checks, keep unknown causes unknown, and do not auto-enable or recreate the item. A user-confirmed storage-only request can finish with readability explicitly unverified.

Account for each confirmed item once as created, updated/unchanged, skipped, or blocked. Pending writes or intended readability mean partial completion. A skipped confirmed item stays pending unless the user drops it. Name the known next action where possible.

Example proposal and completion​

Assume you confirmed that production deployments require maintainer approval, the agent inspected engineering/review-change through get_prompt, and the Team permits the proposed actions. create_agent and update_prompt are advertised, but create_resource is absent.

Proposed starter set for Team engineering

Create engineering/programmer (Agent)
Identity: Software implementer.
Instructions: Implement requested changes, run relevant checks, and report the results.

Update engineering/review-change (Prompt; no arguments)
Current: Review the changes and report issues.
Proposed: Review correctness and regressions. For each actionable finding, give the location,
evidence, impact and suggested correction. State verification limits.

Create docs/deployment-approval.md (Resource; team: engineering)
Content: Production deployments require explicit approval from a maintainer.
Source: The rule you confirmed in this conversation.
Blocked: create_resource is absent; the exclusion cause is unknown.

Please confirm these drafts, changes, and targets. I can create the Agent and update the Prompt
after confirmation. The Resource remains blocked; I will not attempt its unavailable tool.

After confirmation and successful permitted writes:

Guided setup partially completed.
Created: engineering/programmer
Updated: engineering/review-change
Skipped: None
Blocked: docs/deployment-approval.md in Team engineering — create_resource is unavailable;
the exclusion cause is unknown. No Resource write was attempted.
Remaining dashboard action: Assign engineering/programmer to this credential for automatic
selection at task start.

Good to know​

  • Every management call is metered. It counts once against your plan's tool-invocation allowance and shows up in your activity history, including domain rejections inside an executed tool. Authentication and platform-tool admission failures occur before execution usage is recorded.
  • Failures are self-correcting. A domain rejection comes back as a tool error carrying a precise code (for example prompt_name_taken or team_not_found), so a capable agent can read it and adjust rather than give up. See the tool error model.

Next​