@stacksona/mcp-server

Stacksona MCP Server for AI agent approvals, audit logs, and human-in-the-loop governance.

@stacksona/mcp-server connects AI clients like Claude Desktop and other MCP-compatible tools to Stacksona Gate, giving agents a simple way to log activity, request human approval, check decision status, and validate approval tokens before taking sensitive actions.

Use it to add approval workflows, audit trails, and runtime governance to AI agents without rebuilding your agent stack.

What it does

The Stacksona MCP Server exposes Stacksona Gate as MCP tools for AI clients.

With this server, an AI agent can:

• Log agent timeline events for observability and auditing
• Request approval before gated or risky actions
• Wait for a human approve or reject decision
• Fetch decision status by task or thread
• Validate signed one-time approval tokens
• Keep approval and audit data in Stacksona Gate
• Send revision events when a reviewer requests changes to a pending decision

Install

npm install -g @stacksona/mcp-server

Stacksona Gate account:

Stacksona AI Observability and Approval Layer

Requirements

• Node.js 18 or later
• A Stacksona Gate workspace
• A Stacksona API key
• Your Stacksona Gate URL

Environment variables

Example:

STACKSONA_GATE_URL=https://your-gate-subdomain.stacksona.cloud
STACKSONA_API_KEY=sg_your_api_key

Run from the command line

STACKSONA_GATE_URL=https://your-gate-subdomain.stacksona.cloud \
STACKSONA_API_KEY=sg_your_api_key \
stacksona-mcp-server

On Windows PowerShell:

$env:STACKSONA_GATE_URL="https://your-gate-subdomain.stacksona.cloud"
$env:STACKSONA_API_KEY="sg_your_api_key"
stacksona-mcp-server

Claude Desktop setup

Add Stacksona to your Claude Desktop MCP config.

{
  "mcpServers": {
    "stacksona": {
      "command": "stacksona-mcp-server",
      "env": {
        "STACKSONA_GATE_URL": "https://your-gate-subdomain.stacksona.cloud",
        "STACKSONA_API_KEY": "sg_your_api_key"
      }
    }
  }
}

Restart Claude Desktop after updating the config.

Available MCP tools

stacksona_log_event

Log an agent timeline event to Stacksona Gate.

Use this for audit trails, observability, agent activity history, and workflow monitoring.

stacksona_request_decision

Request an approval decision before an agent takes a gated action.

Use this when the agent should pause before doing something sensitive, external, irreversible, expensive, or policy-controlled.

stacksona_request_decision_and_poll

Request a decision and wait for approval or rejection when human review is required.

Use this when the agent should not continue until Stacksona Gate returns an approved or rejected decision.

This tool honors recommended_poll_after_seconds from Stacksona Gate and also supports:

• interval_ms
• timeout_ms

stacksona_get_decision

Fetch the current decision status by thread_id or task_id.

Use this when an agent or client needs to check whether a prior approval request was approved, rejected, or is still pending.

stacksona_validate_approval_token

Validate signed one-time approval tokens.

Use this before executing approved actions that require proof of approval.

stacksona_send_revision

Send a revision event to update a pending review thread after a reviewer has requested changes.

Use this when a reviewer replies to a pending decision with feedback asking the agent to modify its proposal. The agent adjusts its request and calls this tool to push the updated proposal back to the same thread — without opening a new decision request. Gate evaluates the revised payload through the same rule system as a normal decision request.

Required fields: task_id, thread_id, revision_id, workflow_name, task_label, tool_name, subject, request_payload

Optional fields: preview, risk_level, summary, event_summary

Constraints:

• Only valid while the thread is in needs_review or escalated status. Approved or rejected threads cannot be revised.
• Each revision supersedes the previous one on the same thread. Use an incrementing revision_id (e.g. rev-001, rev-002) to track revisions.
• After sending a revision, poll the same thread_id using stacksona_get_decision or stacksona_request_decision_and_poll for the final decision.

Example flow:

1. Agent calls stacksona_request_decision → thread enters needs_review
2. Reviewer replies: "Reduce the refund to $250 and add a return condition"
3. Agent calls stacksona_send_revision with updated subject and request_payload
4. Agent polls the same thread_id until approved or rejected
5. Agent executes the approved action

When to use this MCP server

Use @stacksona/mcp-server when you want AI agents to:

• Ask for approval before taking action
• Create audit logs for agent activity
• Add human review to agent workflows
• Govern high-risk or sensitive actions
• Connect Claude Desktop or another MCP client to Stacksona Gate
• Keep AI decisions traceable across tools and workflows
• Respond to reviewer feedback by revising pending requests without restarting the approval flow

Common examples include:

• Sending emails
• Issuing refunds
• Updating records
• Running automations
• Calling external APIs
• Changing customer data
• Deploying code
• Triggering financial or operational workflows

Polling and webhooks

Use stacksona_request_decision_and_poll when the agent should wait for a human decision.

Webhook delivery is configured in Stacksona Gate Admin, not inside the MCP server.

The MCP server uses Stacksona Gate decision timing hints, including recommended_poll_after_seconds, to avoid unnecessary polling.

Keywords

MCP server, Claude Desktop MCP, AI agent approval, AI governance, human-in-the-loop AI, agent audit logs, Stacksona Gate, AI observability, approval workflow, agent policy layer, runtime AI governance.

Links

• Website: https://stacksona.com
• npm package: @stacksona/mcp-server