Skip to content

Starlight143/mcp-server-stage0-authorization

BranchesTags

Repository files navigation

MCP Server with Stage0 Authorization

A Model Context Protocol (MCP) server demonstrating how to guard tool calls with Stage0 runtime policy validation. This example shows how AI agents can be prevented from executing unauthorized actions before they happen.

Problem Scenario

AI agents can silently escalate from safe operations into dangerous ones:

  • Research → Publication: Agent researches a topic, then publishes findings without approval
  • Analysis → Deployment: Agent investigates an incident, then deploys changes autonomously
  • Drafting → Execution: Agent drafts content, then executes publication workflows
  • Investigation → Loop: Agent keeps retrying failing operations, consuming resources

Stage0 solves this by validating every execution intent before the action happens, returning an external verdict: ALLOW, DENY, or DEFER.

Where Stage0 Fits

┌─────────────────────────────────────────────────────────────────┐
│                     AI Agent Runtime                            │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐                  │
│  │  LLM     │───▶│  Tools   │───▶│ Actions  │                  │
│  └──────────┘    └──────────┘    └──────────┘                  │
│                       │                                         │
│                       ▼                                         │
│              ┌─────────────────┐                                │
│              │    Stage0       │  ◀── External Policy Authority │
│              │  (Guard Layer)  │                                │
│              └─────────────────┘                                │
│                       │                                         │
│                       ▼                                         │
│              ┌─────────────────┐                                │
│              │ ALLOW / DENY /  │                                │
│              │     DEFER       │                                │
│              └─────────────────┘                                │
└─────────────────────────────────────────────────────────────────┘

Stage0 sits between tool invocation and execution - it's NOT part of the agent. The agent cannot self-approve actions. All execution intent MUST be validated via Stage0 /check endpoint.

Why Server-Side Authorization?

A common mistake is to put authorization in the agent's prompt (e.g., "You are not allowed to deploy"). This approach has critical flaws:

Prompt-Based Authorization Server-Side Authorization
Agent can ignore instructions Agent cannot bypass server checks
No audit trail of decisions Every check logged with request_id
Different agents = different behaviors Consistent enforcement across all clients
Can be overridden by user prompts Enforced by external policy authority
No cryptographic proof of policy policy_version ensures reproducibility

The authorization boundary must be in the server-side tool handler, not in the prompt. This repository demonstrates exactly that pattern.

Quick Start

Prerequisites

  • Node.js 18+
  • npm or pnpm
  • (Optional) Stage0 API key from SignalPulse

Installation

# Clone the repository
git clone https://github.com/Starlight143/mcp-server-stage0-authorization.git
cd mcp-server-stage0-authorization

# Install dependencies
npm install

# Copy environment configuration
cp .env.example .env

# Build the TypeScript
npm run build

Configure API Key (Optional)

Edit .env and add your Stage0 API key:

STAGE0_API_KEY=your_api_key_here
STAGE0_BASE_URL=https://api.signalpulse.org

Note: Without an API key, the server uses simulated Stage0 responses. This is useful for testing the integration flow.

Run the Demo

# Demo 1: ALLOW scenario - research tool call
npm run demo:allow

# Demo 2: DENY scenario - publish tool call  
npm run demo:deny

# Demo 3: DEFER scenario - loop threshold exceeded
npm run demo:defer

Expected Output

ALLOW Example (Research)

======================================================================
DEMO: ALLOW Scenario - Research Tool Call
======================================================================

Scenario: An agent wants to research a topic and return
informational summary. This is a low-risk operation.

Calling Stage0 to check authorization...

Response from Stage0:
----------------------------------------------------------------------
Verdict:        ALLOW
Decision:       GO
Reason:         Informational operation with no high-risk side effects
Request ID:     a1b2c3d4-e5f6-7890-abcd-ef1234567890
Policy Version: simulated-v1.0.0
Risk Score:     15
High Risk:      false
----------------------------------------------------------------------

✅ TOOL CALL ALLOWED

The agent can proceed to execute the research tool.
This is safe because:
- No side effects (publish, deploy, etc.)
- Informational operation only
- No guardrail violations

DENY Example (Publish)

======================================================================
DEMO: DENY Scenario - Publish Tool Call
======================================================================

Scenario: An agent attempts to publish content to a public
channel without proper authorization. This is a high-risk
operation that should be blocked.

Calling Stage0 to check authorization...

Response from Stage0:
----------------------------------------------------------------------
Verdict:        DENY
Decision:       NO_GO
Reason:         HIGH severity: SIDE_EFFECTS_NEED_GUARDRAILS - 'publish' 
                side effect requires approval guardrails
Request ID:     b2c3d4e5-f6a7-8901-bcde-f12345678901
Policy Version: simulated-v1.0.0
Risk Score:     85
High Risk:      true

Issues detected:
  [HIGH] SIDE_EFFECTS_NEED_GUARDRAILS: Side effects [publish] require 
         approval guardrails
----------------------------------------------------------------------

⛔ TOOL CALL BLOCKED

The agent is NOT allowed to execute this tool.
This is correct because:
- "publish" side effect requires approval guardrails
- No human approval was provided
- Publishing without review can cause trust/compliance issues

DEFER Example (Vague Request)

======================================================================
DEMO: DEFER Scenario - Unclear/Vague Request
======================================================================

Scenario: An agent receives a vague request without clear
success criteria or value proposition. Stage0 DEFERs to
request more context before proceeding.

Calling Stage0 to check authorization...

Response from Stage0:
----------------------------------------------------------------------
Verdict:        DEFER
Decision:       DEFER
Reason:         UNCLEAR_VALUE_SIGNAL: Task appears under-specified 
                for reliable value delivery.
Request ID:     c3d4e5f6-a7b8-9012-cdef-123456789012
Policy Version: simulated-v1.0.0
Risk Score:     35

Clarifying questions:
  ? What is the specific outcome you want to achieve?
  ? What constraints or requirements should be considered?
----------------------------------------------------------------------

⏸️ TOOL CALL DEFERRED

The agent should NOT proceed automatically.
Human review is required because:
- Request is too vague to evaluate value
- Success criteria are unclear
- More context is needed before execution

Note: The actual verdict depends on your Stage0 plan and policy configuration:

  • Pro plans may return DEFER for vague requests with clarifying_questions
  • Free/Starter plans may return ALLOW with clarifying questions or DENY depending on policy settings
  • The simulated response (without API key) demonstrates the expected DEFER behavior

Where request_id and policy_version Appear

Every Stage0 /check response includes:

Field Description Location
request_id Unique identifier for this authorization request Use for audit logs, debugging, and traceability
policy_version Version of the policy pack used for evaluation Use for compliance and reproducibility

These fields are returned in the API response:

{
  "verdict": "DENY",
  "decision": "NO_GO",
  "reason": "...",
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "policy_version": "v1.2.3",
  "risk_score": 85,
  "high_risk": true
}

Running as MCP Server

To use this as an MCP server with Claude Desktop or other MCP clients:

1. Build the server

npm run build

2. Add to Claude Desktop config

Edit the Claude Desktop config file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "stage0-authorization": {
      "command": "node",
      "args": ["<REPO_PATH>/dist/index.js"],
      "env": {
        "STAGE0_API_KEY": "your_api_key_here",
        "STAGE0_BASE_URL": "https://api.signalpulse.org"
      }
    }
  }
}

Replace <REPO_PATH> with the actual path to your cloned repository.

3. Available Tools

Tool Description Risk Level Context-Aware
research-topic Research and summarize a topic Low No
publish-content Publish content to a channel High No
deploy-changes Deploy to environment High Yes (actor_role)
managed-deploy Deploy with full authorization context High Yes (all fields)
retry-workflow Retry a failing workflow Medium Yes (retry_count)
check-authorization Check if action would be authorized N/A Optional

Authorization Context

The managed-deploy tool demonstrates the four critical context fields that should be passed from upstream:

Field Description Example Values
actor_role Role of the entity performing the action admin, developer, viewer
approval_status Whether the action has been approved approved, pending, none
environment Target environment production, staging, development
resource_scope Scope of resources affected all, team-a, service-x

Example: Role-Based Deployment Control

const context: Stage0Context = {
  actor_role: 'developer',      // Who is performing the action
  approval_status: 'pending',   // Has this been approved?
  environment: 'production',    // Where is this deploying?
  resource_scope: 'team-a',     // What resources are affected?
};

const response = await stage0.checkGoal(
  'Deploy authentication service to production',
  {
    sideEffects: ['deploy'],
    context,
    successCriteria: ['Deployment completes successfully'],
  }
);

This context enables policy rules like:

  • viewer role → DENY all deployments
  • developer role → ALLOW staging, DENY production without approval
  • admin role → ALLOW all with approval_status: approved

Integration Guide

To add Stage0 authorization to your MCP server:

Basic Pattern

import { Stage0Client, Stage0Context } from './stage0-client.js';

const stage0 = new Stage0Client();

server.tool('my-tool', 'Description', schema, async (params) => {
  // 1. Check authorization before execution
  const response = await stage0.checkGoal(
    'Description of what this tool does',
    {
      sideEffects: ['publish'],
      successCriteria: ['Task completes successfully'],
      constraints: ['approval_required'],
    }
  );

  // 2. Handle the verdict
  if (response.verdict === 'DENY') {
    return {
      content: [{ type: 'text', text: `Blocked: ${response.reason}` }],
    };
  }

  if (response.verdict === 'DEFER') {
    return {
      content: [{ type: 'text', text: `Deferred: ${response.reason}` }],
    };
  }

  // 3. Execute only if ALLOWED
  const result = await doSomething(params);
  return {
    content: [{ type: 'text', text: result }],
  };
});

With Authorization Context

For privileged operations, pass context from upstream:

server.tool('deploy-service', 'Deploy a service', {
  serviceName: z.string(),
  environment: z.enum(['staging', 'production']),
  actorRole: z.enum(['admin', 'developer', 'viewer']),
}, async ({ serviceName, environment, actorRole }) => {
  const context: Stage0Context = {
    actor_role: actorRole,
    environment,
    approval_status: 'none', // Would come from your approval system
  };

  const response = await stage0.checkGoal(
    `Deploy ${serviceName} to ${environment}`,
    {
      sideEffects: ['deploy'],
      context,
      successCriteria: ['Deployment succeeds'],
    }
  );

  if (response.verdict !== 'ALLOW') {
    return {
      content: [{ 
        type: 'text', 
        text: `⛔ ${response.verdict}: ${response.reason}\n\nRequest ID: ${response.request_id}` 
      }],
    };
  }

  // Execute deployment
  return executeDeployment(serviceName, environment);
});

Why This Matters

Without Stage0 With Stage0
Agent executes every planned step Agent validates before execution
Silent escalation to dangerous actions External authority checks intent
Self-approved publication/deployment Human approval required
Runaway retry loops Loop thresholds enforced
Post-hoc detection only Prevention before execution

Running Tests

This repository includes comprehensive smoke tests:

# Run all tests (uses simulated mode without API key)
npm test

# Run tests with real API
STAGE0_API_KEY=your_api_key npm test

# Run tests in watch mode
npm run test:watch

Tests cover:

  • ALLOW/DENY/DEFER verdict scenarios
  • Context propagation (actor_role, environment, etc.)
  • Error handling and edge cases
  • Real API integration (when API key provided)

Related Examples

This example is part of the SignalPulse framework quickstart collection:

License

MIT

About

MCP server demonstrating server-side authorization with Stage0 runtime policy validation

signalpulse.org/

Topics

security mcp authorization ai-safety stage0 model-context-protocol runtime-policy

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 1

v1.0.0 - Initial Release Latest
Mar 23, 2026

Packages

 
 
 

Contributors

Languages