setup

Return the canonical, versioned instruction for installing or repairing apistash's persistent task-start setup in the current client.

Call apistash/setup only when the user asks to set up, install, repair, or update apistash. Do not call it automatically at the start of an ordinary task. To install task-start setup, ask your agent to "set up apistash" after connecting it to apistash. The task-start setup guide lists the native project scope and verification step for each supported client.

Parameters

Pass an empty object:

{}

The tool accepts no client, file path, scope, or installation choice. The local agent discovers those from the client it is actually running in. Clients may also omit the top-level MCP arguments member or send it as null; both are treated as {}.

Response

Field	Type	Description
instruction_id	string	Stable identity of the managed instruction: apistash-bootstrap.
instruction_version	number	Version of the instruction and its installation rules.
instruction	string	The canonical task-start instruction.
portable_managed_block	string	Portable labelled form of the instruction when native instruction metadata is unavailable.
guided_onboarding	object	Optional agent-led interview, inspection, proposal, confirmation, and reporting workflow.
installation	object	Rules the local agent must follow when applying the instruction.
installation.operation	string	add_or_update_persistent_instruction.
installation.target	string	client_native_persistent_instruction_mechanism.
installation.scope	string	narrowest_scope_matching_connection_and_user_intent.
installation.on_write_unavailable	string	show_instruction_and_report_not_installed.

For version 2, a successful call returns:

{
	"instruction_id": "apistash-bootstrap",
	"instruction_version": 2,
	"instruction": "At the start of each task, if `apistash/bootstrap` is available, make one initial call before substantive work. Always specify primary_agent. A primary starts with {\"primary_agent\":true}: use its credential-assigned Agent unless the user explicitly directs otherwise; if unassigned, choose a suitable definition or continue roleless. Report an unavailable assignment without substituting a role. A subagent must use primary_agent:false and the parent-provided agent_selection: \"named\" with agent:\"<name>\", \"self\" to choose its own suitable definition, or \"none\" to work without one. When delegating, explicitly supply that selection mode and any required name; never inherit the credential assignment. To load an allowed choice, call bootstrap again with the same primary_agent, agent_selection:\"named\", and agent:\"<name>\". A self-selecting subagent with no suitable definition must report to its direct parent and await its decision, not continue roleless; the parent may explicitly permit none, revise the delegation, or consult the user within its authority. Primary and self calls include an independent Agent catalog; other calls can request it with request_agent_catalog:true while keeping the same role arguments. Seeing the catalog does not permit changing role or delegating work. Follow-up selection and catalog calls are allowed. If the initial call is unavailable, denied, or fails, report any blocked delegated role requirement, continue only work independent of that requirement, and do not retry automatically.",
	"portable_managed_block": "[apistash-managed-instruction id=\"apistash-bootstrap\" version=\"2\"]\nAt the start of each task, if `apistash/bootstrap` is available, make one initial call before substantive work. Always specify primary_agent. A primary starts with {\"primary_agent\":true}: use its credential-assigned Agent unless the user explicitly directs otherwise; if unassigned, choose a suitable definition or continue roleless. Report an unavailable assignment without substituting a role. A subagent must use primary_agent:false and the parent-provided agent_selection: \"named\" with agent:\"<name>\", \"self\" to choose its own suitable definition, or \"none\" to work without one. When delegating, explicitly supply that selection mode and any required name; never inherit the credential assignment. To load an allowed choice, call bootstrap again with the same primary_agent, agent_selection:\"named\", and agent:\"<name>\". A self-selecting subagent with no suitable definition must report to its direct parent and await its decision, not continue roleless; the parent may explicitly permit none, revise the delegation, or consult the user within its authority. Primary and self calls include an independent Agent catalog; other calls can request it with request_agent_catalog:true while keeping the same role arguments. Seeing the catalog does not permit changing role or delegating work. Follow-up selection and catalog calls are allowed. If the initial call is unavailable, denied, or fails, report any blocked delegated role requirement, continue only work independent of that requirement, and do not retry automatically.\n[/apistash-managed-instruction]",
	"installation": {
		"operation": "add_or_update_persistent_instruction",
		"target": "client_native_persistent_instruction_mechanism",
		"scope": "narrowest_scope_matching_connection_and_user_intent",
		"on_ambiguous_target_or_scope": "ask_user",
		"match_existing_by": "instruction_id",
		"on_missing": "add_once",
		"on_older_version": "replace_managed_instruction_only",
		"on_same_version": "leave_unchanged",
		"on_newer_version": "leave_unchanged",
		"preserve_unrelated_content": true,
		"verify_after_write": true,
		"report_target_scope_and_outcome": true,
		"on_write_unavailable": "show_instruction_and_report_not_installed"
	},
	"guided_onboarding": {
		"mode": "offer_after_general_setup",
		"opening_question": "What will you mainly use apistash for?",
		"collect": [
			"primary_jobs_and_outcomes",
			"ownership_target",
			"technology_and_operating_context",
			"approval_boundaries",
			"desired_recurring_roles"
		],
		"workflow": [
			"call_bootstrap_with_primary_agent_true_for_primary_task",
			"offer_ownership_targets_from_own_space_availability_and_bound_teams",
			"inspect_advertised_management_tools",
			"inspect_relevant_existing_content",
			"disclose_unavailable_inspection_and_duplicate_risk",
			"obtain_canonical_editable_data_and_required_versions_before_proposing_updates",
			"propose_smallest_useful_starter_set",
			"show_drafts_and_material_changes_with_targets",
			"report_known_permission_blockers",
			"ask_for_explicit_confirmation",
			"create_or_update_confirmed_items_only",
			"verify_resource_mcp_readability_when_possible",
			"report_created_updated_unchanged_skipped_and_blocked_items",
			"report_pending_resource_access_and_dashboard_assignment_or_publication_steps"
		],
		"never_store": [
			"secrets_or_credentials",
			"sensitive_personal_data_without_explicit_request",
			"unverified_assumptions",
			"transient_task_state",
			"empty_placeholder_resources"
		]
	}
}

Installation behavior

The receiving local agent applies the response through its own client-native persistent instruction mechanism. It must:

1. Identify the actual host/client and its supported persistent-instruction mechanism.
2. Use the narrowest scope that applies to this apistash connection and matches the user's intent. If more than one target or scope is plausible, ask the user before writing.
3. Find an existing apistash-managed instruction by its stable ID, not by similar wording.
4. Add one managed instruction when absent. Update only that managed instruction when its version is older; leave a same or newer version unchanged. Never duplicate or downgrade it.
5. Preserve all unrelated instructions and content outside the managed instruction.
6. Verify the saved state and report the client, target, scope, and whether the outcome was created, updated, unchanged, or not_installed.
7. When the client has no writable persistent-instruction mechanism available, show the canonical instruction and report that it was not installed.

Guided onboarding

After general setup, the local agent offers the interview once in the current conversation. It starts with “What will you mainly use apistash for?” and calls Bootstrap with primary_agent: true for the primary task before offering ownership choices. Only an available own space and the returned bound teams are options. A repair-only request does not start onboarding unless you also ask for it.

The agent inspects relevant content, obtains canonical editable data before proposing updates, and shows the smallest useful set of concrete drafts or material changes with their exact targets. It asks for confirmation before governed writes, following Bootstrap's content workflow. If inspection is unavailable, it discloses the duplicate risk and obtains explicit creation consent. No onboarding state or customer content is written by this system tool. Agent assignment, organization-catalogue publication, and connector secrets remain dashboard actions. See guided setup.

Errors

Error	Cause
invalid_params	Arguments were not an empty object.
method_not_found	The tool is absent or deprecated.
internal_error	An unexpected server error occurred.

Notes

• setup is an authenticated system tool and does not require Tools or any tool-selection or tool-policy entry. Authentication, rate limits, and usage quotas still apply.
• setup does not need Agents: instruction installation and the onboarding offer do not depend on Agent use. A later bootstrap needs Agents only when it selects or returns Agent content.
• setup returns instructions for local installation and optional onboarding. apistash does not write the client's files or settings itself.
• After installation, the saved instruction makes one initial Bootstrap call with explicit caller identity and role-selection rules. It permits follow-up selection and catalog calls and requires blocked delegated roles to be reported without automatic fallback. See the task-start workflow.