Netskope NPA MCP Server

1# Netskope NPA MCP Server
2 
3A comprehensive Model Context Protocol (MCP) server for managing Netskope Private Access (NPA) infrastructure through AI-powered automation.
4 
5## 📚 Complete Documentation
6 
7This project includes extensive documentation organized for easy navigation:
8 
9**👉 [Start with the Complete Documentation](./docs/README.md)** - Overview and navigation guide
10 
11### Quick Access Links
12 
13| Category | Description | Link |
14|----------|-------------|------|
15| **🏗️ Architecture** | Server design and patterns | [Server Architecture](./docs/architecture/server-architecture.md) |
16| **🛠️ Tools Reference** | Complete tool documentation | [Publisher Tools](./docs/tools/publisher-tools.md), [Private App Tools](./docs/tools/private-app-tools.md), [Policy Tools](./docs/tools/policy-tools.md) |
17| **🔄 Workflows** | Common automation patterns | [Common Workflows](./docs/workflows/common-workflows.md) |
18| **💼 Real Examples** | Complete use cases | [Real-World Examples](./docs/examples/real-world-examples.md) |
19 
20## Tool Overview
21 
22The MCP server provides **84 specialized tools** across 10 categories:
23 
24| Category | Tools | Primary Use Cases |
25|----------|-------|------------------|
26| **Publishers** | 9 tools | Infrastructure deployment and management |
27| **Private Apps** | 15 tools | Application lifecycle and configuration |
28| **Local Brokers** | 7 tools | Network connectivity and routing |
29| **Policy Management** | 6 tools | Access control and security rules |
30| **SCIM Integration** | 5 tools | Identity and user management |
31| **Upgrade Profiles** | 7 tools | Automated maintenance scheduling |
32| **Steering** | 3 tools | Traffic routing and associations |
33| **Alerts** | 2 tools | Event monitoring and notifications |
34| **Search** | 2 tools | Resource discovery and querying |
35| **Validation** | 2 tools | Configuration compliance |
36 
37## Real-World Usage Examples
38 
39### 🏢 "Set up complete NPA infrastructure for our new London office"
40**AI Response**: Executes comprehensive deployment workflow
41- ✅ Creates publisher with auto-upgrade profile
42- ✅ Configures local broker for internal routing  
43- ✅ Sets up core business applications (CRM, ERP, File Server)
44- ✅ Creates access policies with SCIM group validation
45- ✅ Enables monitoring and discovery for office network
46- ✅ Generates registration token for field deployment
47 
48### 🚨 "URGENT: Security incident - lock down HR/Finance apps immediately"
49**AI Response**: Emergency security response workflow
50- ✅ Identifies all HR/Finance applications automatically
51- ✅ Creates emergency policy group with highest priority
52- ✅ Blocks access for all users except incident response team
53- ✅ Enhances monitoring for security events
54- ✅ Tags applications for incident tracking
55 
56### 📊 "Perform comprehensive compliance audit of our NPA environment"
57**AI Response**: Automated compliance assessment
58- ✅ Audits all publishers for version compliance
59- ✅ Identifies applications without access policies
60- ✅ Validates SCIM group references in policies
61- ✅ Generates compliance score and remediation plan
62- ✅ Creates detailed findings report with priorities
63 
64## Quick Start
65 
661. **Environment Setup**
67   ```bash
68   export NETSKOPE_BASE_URL="https://your-tenant.goskope.com"
69   export NETSKOPE_TOKEN="your-api-token"
70   ```
71 
722. **Install and Run**
73   ```bash
74   npm install
75   npm run build
76   npm start
77   ```
78 
793. **Connect via MCP Client**
80   ```json
81   {
82     "mcpServers": {
83       "netskope-npa": {
84         "command": "node",
85         "args": ["/path/to/ns-private-access-mcp/build/index.js"],
86         "env": {
87           "NETSKOPE_BASE_URL": "https://your-tenant.goskope.com",
88           "NETSKOPE_TOKEN": "your-api-token"
89         }
90       }
91     }
92   }
93   ```
94 
95## Key Features
96 
97### 🤖 AI-Native Design
98- Tools designed for LLM interaction with clear descriptions
99- Automatic parameter validation and transformation
100- Rich error context for troubleshooting
101 
102### 🔄 Workflow Orchestration
103- Tools automatically coordinate with each other
104- Built-in retry logic and error recovery
105- Transactional operations where possible
106 
107### 🛡️ Production Ready
108- Comprehensive input validation using Zod schemas
109- Rate limiting and API quota management
110- Detailed logging and monitoring
111 
112### 🔗 Integration Patterns
113- SCIM integration for identity resolution
114- Search tools for resource discovery
115- Validation tools for compliance checking
116 
117## Installation Options
118 
119### NPM Package
120```bash
121npm install @johnneerdael/ns-private-access-mcp
122```
123 
124### Local Development
125```bash
126git clone https://github.com/johnneerdael/ns-private-access-mcp.git
127cd ns-private-access-mcp
128npm install
129npm run build
130```
131 
132## Architecture Highlights
133 
134### Tool Composition
135Tools are designed to work together through well-defined interfaces:
136 
137```typescript
138// Example: Creating a private app with validation and tagging
1391. validateName() -> Check app name compliance
1402. searchPublishers() -> Find target publisher
1413. createPrivateApp() -> Create the application  
1424. createPrivateAppTags() -> Add organizational tags
1435. updatePublisherAssociation() -> Associate with publishers
144```
145 
146### Schema-Driven Validation
147Every tool uses Zod schemas for type safety and validation:
148 
149```typescript
150const createAppSchema = z.object({
151  app_name: z.string().min(1).max(64),
152  host: z.string().url(),
153  protocols: z.array(protocolSchema),
154  clientless_access: z.boolean()
155});
156```
157 
158### Error Resilience
159Built-in patterns for handling common issues:
160- Automatic parameter extraction from MCP objects
161- Retry logic with exponential backoff
162- Graceful degradation for partial failures
163 
164## Credits
165 
166- **John Neerdael** (Netskope Private Access Product Manager)  
167- **Mitchell Pompe** (Chief Netskope Solutions Engineer for NL)
168 
169## Getting Help
170 
171- **Documentation Issues**: Open an issue on GitHub
172- **Feature Requests**: Create a feature request issue
173- **Bug Reports**: Use the bug report template
174- **Security Issues**: See [SECURITY.md](./docs/SECURITY.md)
175 
176---
177 
178*This MCP server transforms complex Netskope NPA management into simple, AI-driven conversations.*
179