johnneerdael/netskope-mcp

A comprehensive Model Context Protocol (MCP) server for managing Netskope Private Access (NPA) infrastructure through AI-powered automation.

📚 Complete Documentation

This project includes extensive documentation organized for easy navigation:

👉 Start with the Complete Documentation - Overview and navigation guide

Quick Access Links

Category	Description	Link
🏗️ Architecture	Server design and patterns	Server Architecture
🛠️ Tools Reference	Complete tool documentation	Publisher Tools, Private App Tools, Policy Tools
🔄 Workflows	Common automation patterns	Common Workflows
💼 Real Examples	Complete use cases	Real-World Examples

Tool Overview

The MCP server provides 84 specialized tools across 10 categories:

Category	Tools	Primary Use Cases
Publishers	9 tools	Infrastructure deployment and management
Private Apps	15 tools	Application lifecycle and configuration
Local Brokers	7 tools	Network connectivity and routing
Policy Management	6 tools	Access control and security rules
SCIM Integration	5 tools	Identity and user management
Upgrade Profiles	7 tools	Automated maintenance scheduling
Steering	3 tools	Traffic routing and associations
Alerts	2 tools	Event monitoring and notifications
Search	2 tools	Resource discovery and querying
Validation	2 tools	Configuration compliance

Real-World Usage Examples

🏢 "Set up complete NPA infrastructure for our new London office"

AI Response: Executes comprehensive deployment workflow

• ✅ Creates publisher with auto-upgrade profile
• ✅ Configures local broker for internal routing
• ✅ Sets up core business applications (CRM, ERP, File Server)
• ✅ Creates access policies with SCIM group validation
• ✅ Enables monitoring and discovery for office network
• ✅ Generates registration token for field deployment

🚨 "URGENT: Security incident - lock down HR/Finance apps immediately"

AI Response: Emergency security response workflow

• ✅ Identifies all HR/Finance applications automatically
• ✅ Creates emergency policy group with highest priority
• ✅ Blocks access for all users except incident response team
• ✅ Enhances monitoring for security events
• ✅ Tags applications for incident tracking

📊 "Perform comprehensive compliance audit of our NPA environment"

AI Response: Automated compliance assessment

• ✅ Audits all publishers for version compliance
• ✅ Identifies applications without access policies
• ✅ Validates SCIM group references in policies
• ✅ Generates compliance score and remediation plan
• ✅ Creates detailed findings report with priorities

Quick Start

1. Environment Setup

   export NETSKOPE_BASE_URL="https://your-tenant.goskope.com"
   export NETSKOPE_TOKEN="your-api-token"
   

2. Install and Run

   npm install
   npm run build
   npm start
   

3. Connect via MCP Client

   {
     "mcpServers": {
       "netskope-npa": {
         "command": "node",
         "args": ["/path/to/privateaccess-mcp/build/index.js"],
         "env": {
           "NETSKOPE_BASE_URL": "https://your-tenant.goskope.com",
           "NETSKOPE_TOKEN": "your-api-token"
         }
       }
     }
   }
   

Key Features

🤖 AI-Native Design

• Tools designed for LLM interaction with clear descriptions
• Automatic parameter validation and transformation
• Rich error context for troubleshooting

🔄 Workflow Orchestration

• Tools automatically coordinate with each other
• Built-in retry logic and error recovery
• Transactional operations where possible

🛡️ Production Ready

• Comprehensive input validation using Zod schemas
• Rate limiting and API quota management
• Detailed logging and monitoring

🔗 Integration Patterns

• SCIM integration for identity resolution
• Search tools for resource discovery
• Validation tools for compliance checking

Installation Options

NPM Package

npm install @johnneerdael/ns-private-access-mcp

Local Development

git clone https://github.com/johnneerdael/privateaccess-mcp.git
cd privateaccess-mcp
npm install
npm run build

Generic JSON client config

For clients that take a JSON map (Cursor, Windsurf, custom hosts):

{
  "mcpServers": {
    "netskope": {
      "url": "https://YOUR-MCP-HOST.example.com/mcp",
      "headers": {
        "X-Netskope-Tenant": "https://YOUR-TENANT.goskope.com",
        "Authorization": "Bearer YOUR_NETSKOPE_API_TOKEN"
      }
    }
  }
}

Self-hosting

Prefer to run your own instance? Two compose files are shipped:

File	Purpose	Command
docker-compose.yml	Run the prebuilt multi-arch image from GHCR.	docker compose up -d
docker-compose.build.yml	Build from local sources (for development).	docker compose -f docker-compose.build.yml up --build

One-liners without compose:

# Prebuilt image from GHCR
docker run --rm -p 3000:3000 ghcr.io/johnneerdael/privateaccess-mcp:latest

# Build and run from a local checkout
docker build -t netskope-mcp:local .
docker run --rm -p 3000:3000 netskope-mcp:local

# Or just run the Node entry directly
npm run build && PORT=3000 node dist/cli-http.js

The container exposes /mcp (streamable HTTP) and /healthz (liveness). Useful env vars:

Var	Purpose
PORT / HOST	Bind address (default 0.0.0.0:3000).
PUBLIC_URL	Canonical public origin (e.g. https://YOUR-MCP-HOST.example.com). Surfaced in /healthz and the startup log; reserved for future OAuth/well-known metadata. Safe to omit.
CORS_ORIGIN	Comma-separated allowlist for browser-based MCP clients (e.g. https://claude.ai). Defaults to *. Not relevant for CLI clients (Claude Code, Codex, Cursor) or when running behind a reverse proxy that doesn't itself need CORS.
NETSKOPE_BASE_URL / NETSKOPE_API_TOKEN	Optional fallback credentials, used only when a client omits the headers. Set both for single-tenant deployments; leave both unset for multi-tenant self-hosting (recommended for shared self-hosted deployments).

Architecture Highlights

Tool Composition

Tools are designed to work together through well-defined interfaces:

// Example: Creating a private app with validation and tagging
1. validateName() -> Check app name compliance
2. searchPublishers() -> Find target publisher
3. createPrivateApp() -> Create the application  
4. createPrivateAppTags() -> Add organizational tags
5. updatePublisherAssociation() -> Associate with publishers

Schema-Driven Validation

Every tool uses Zod schemas for type safety and validation:

const createAppSchema = z.object({
  app_name: z.string().min(1).max(64),
  host: z.string().url(),
  protocols: z.array(protocolSchema),
  clientless_access: z.boolean()
});

Error Resilience

Built-in patterns for handling common issues:

• Automatic parameter extraction from MCP objects
• Retry logic with exponential backoff
• Graceful degradation for partial failures

Credits

• John Neerdael (Netskope Private Access Product Manager)
• Mitchell Pompe (Chief Netskope Solutions Engineer for NL)

Getting Help

• Documentation Issues: Open an issue on GitHub
• Feature Requests: Create a feature request issue
• Bug Reports: Use the bug report template
• Security Issues: See SECURITY.md

---

This MCP server transforms complex Netskope NPA management into simple, AI-driven conversations.