Tool reference

Every tool StackHangar's MCP server offers to agents, with parameters, what each returns and what none of them ever returns.

StackHangar's MCP server gives an agent nine tools. None of them returns a credential value, an item name or a project name.

Refs are opaque IDs (UUIDs). You can copy a project's ref from the Agents page when you create a manual token.

#Summary

Tool	Read only	What it does
`list_scope`	Yes	Lists the project refs the agent may use.
`request_credential_entry`	No	Asks you to store a new key.
`request_credential_access`	No	Asks to use a stored key.
`get_request_status`	Yes	Checks one of those two requests.
`request_secret`	No	Asks you to put a secret into an environment variable. See Secret requests.
`get_secret_request_status`	Yes	Checks a secret request. See Secret requests.
`propose_playbook`	No	Proposes a rotation or leaked-key response.
`get_playbook_status`	Yes	Checks a proposal and the steps the agent may run.
`report_step_result`	No	Tells you what the agent ran for one step.

#list_scope

Takes no parameters.

Returns the agent's name and the project refs it may use.

Never returns project names. They are encrypted.

#request_credential_entry

Parameter	Type	Description
`project_ref`	UUID	A project ref from `list_scope`.
`description`	text, up to 300 characters	What the credential is, for example "OpenAI project key for the dev environment".

Returns a request ID, a one-time approval link and its expiry (10 minutes). Show the link to the user. You answer it as described in Approve a request.

Never accepts or returns a value. A description that looks like a key is refused.

#request_credential_access

Parameter	Type	Description
`project_ref`	UUID	A project ref from `list_scope`.
`description`	text, up to 300 characters	What the agent needs and why.

Returns a request ID, a one-time approval link and its expiry (10 minutes). The user picks the key and sees it in their own browser.

Never returns the value.

#get_request_status

Parameter	Type	Description
`request_id`	UUID	A request ID from one of the two tools above.

Returns pending, approved, denied or expired, and on approval an item reference.

Never returns a value. It doesn't answer for secret requests, which have their own status tool.

#request_secret and get_secret_request_status

These two tools ask you to put a secret into an environment variable at Vercel, GitHub or Netlify, and report what happened. See Secret requests for their parameters and outcomes. They never return a value.

#propose_playbook

Parameter	Type	Description
`project_ref`	UUID	A project ref from `list_scope`.
`playbook`	`rotate` or `leaked-key`	Which playbook to run.
`item_refs`	list of exactly one UUID	The item the playbook is for, from an approved credential request.
`description`	text, up to 300 characters	Why, in a sentence. Shown to you after "Agent says:".

Returns a proposal ID, a one-time approval link and its expiry (10 minutes). See Playbook proposals.

Never accepts or returns a value. The agent can't propose any other playbook.

#get_playbook_status

Parameter	Type	Description
`proposal_id`	UUID	A proposal ID from `propose_playbook`.

Returns:

status: pending, approved, denied, expired, completed or cancelled.
playbook: which playbook.
agentStepsEnabled: false on Free, or before approval. When false, you run every step and reports are refused.
steps: empty until approved. Each has a stepRef, a kind (redeploy, verify or revoke), whether it is destructive, and a status: waiting, ready, authorized, reported-done, reported-failed, done or skipped.
activeUntil: when an approved proposal stops accepting reports, or null.

The agent should run a step only when its status is ready or authorized. Revoke needs your passkey first.

Never returns a value, an item name or a project name.

#report_step_result

Parameter	Type	Description
`proposal_id`	UUID	The proposal.
`step_ref`	text	A `stepRef` from `get_playbook_status`.
`outcome`	`done` or `failed`	What happened.
`note`	text, up to 300 characters, optional	What the agent ran and what happened.

Returns the step's new status.

Accepted only for a step that is ready, authorized or already reported by this agent, at most 5 times per step. It needs a Solo plan. At most 120 reports an hour count towards the limit, accepted or refused. A note that looks like a key is refused.

#Errors

Tools return plain-language errors. Common ones:

The agent isn't allowed to use that project. You can change an agent's projects by disconnecting it and connecting it again.
Too many requests are waiting for you (5), or too many this hour (30).
A description looks like it contains a credential.
The agent was disconnected.
On the Free plan, only the first connected agent can propose playbooks or request secrets.

Something missing or wrong on this page? Tell us.