GetSetPOx MCP Server

Drive Microsoft Entra, Global Secure Access, Intune & IGA proof-of-concepts from your AI agent.

A Model Context Protocol (MCP) server that exposes Microsoft Graph-powered tools for Entra ID, Global Secure Access (Internet Access), Identity Governance (IGA), and Intune — so an AI agent can stand up and operate Microsoft identity & security POCs through natural language.

Overview · Tool Catalog · Quick Start · VS Code Setup · Configuration · Development

🎯 Overview

GetSetPOx is a Python-based MCP server built for rapid Microsoft POC delivery. Connect it to any MCP-compatible client (VS Code, Claude, or your own agent) and drive real Microsoft Graph operations — list and create Entra users/groups/devices, configure Global Secure Access web content filtering, manage Intune devices and app deployments, and build Identity Governance access packages — all through tool calls instead of clicking through portals.

Highlights:

✨ Clean, modular service-per-domain architecture — easy to extend with new tools
🔄 Dual transport: STDIO (default) and HTTP
🛡️ Full OAuth2 / MSAL auth for Microsoft Graph (application & delegated modes)
🧪 Built-in permission diagnostics that test 19 critical Graph permissions with live API calls
📦 Ships as source or a standalone executable (no Python install required)
📝 Structured logging and environment-variable configuration

What it's for: turning a multi-step Microsoft identity/security POC into a handful of agent instructions — reproducibly, with the same Graph calls every time.

Who it's for

You are…	Use GetSetPOx to…
An identity / security pre-sales engineer	Spin up Entra + GSA + Intune demo environments fast, from your agent.
A Microsoft 365 / Entra admin	Script repeatable Graph operations (users, groups, devices, policies) without bespoke code.
An AI-agent / MCP builder	Plug a battle-tested Microsoft Graph toolset into your agent over a standard protocol.
A POC / lab author	Automate end-to-end Web Content Filtering and access-package setups in one call.

🧰 Tool & Service Catalog

🧪 Test & Diagnostics

hello_world — simple greeting service for testing MCP connectivity
echo — echo service with metadata for validation and debugging
check_token_permissions — comprehensive Microsoft Graph permission diagnostics; tests 19 critical permissions with real API calls and returns actionable success/failure reports

👤 Entra ID (EID) Management

EID_listUsers — list all users from Microsoft Entra ID
EID_getUser — get a specific user by ID or userPrincipalName
EID_searchUsers — search users by display name or email
EID_listDevices — list all devices (Entra Joined, Hybrid Joined, Registered, Compliant)
EID_getDevice — get specific device details by ID
EID_getGroups / EID_getGroup — list groups (paginated) or fetch one by ID
EID_getGroupMembers — get members of a specific group
EID_searchGroups — search groups by display name
EID_createUserGroups — create and manage security groups with users and nested groups

🛂 Identity Governance & Administration (IGA)

IGA_listAccessPackages — list all access packages from Entitlement Management
IGA_createAccessCatalog — create new access package catalogs
IGA_createAccessPackage — create new access packages
IGA_addResourceGrouptoPackage — add Entra groups as resources to access packages

💻 Intune Device Management

IN_listIntuneManagedDevices — list all Intune-managed devices
IN_getManagedDeviceDetails — detailed device info (compliance, enrollment, sync status)
IN_listDeviceCompliancePolicies — list all device compliance policies
IN_listDeviceConfigurationProfiles — list all configuration profiles
IN_syncManagedDevice — trigger a device sync with Intune
IN_prepGSAWinClient — prepare the Global Secure Access Windows Client for deployment
IN_intuneAppAssignment — assign Win32 apps to device groups with deployment settings

🌐 Global Secure Access — Internet Access (IA)

IA_checkInternetAccessForwardingProfile — check forwarding profile status
IA_enableInternetAccessForwardingProfile — enable/disable forwarding profiles
IA_createFilteringPolicy — create web-category filtering policies
IA_createFilteringProfile — create filtering profiles
IA_linkPolicyToFilteringProfile — link policies to profiles with logging
IA_createConditionalAccessPolicy — create CA policies for filtering profiles
IA_TLSPOCV2 — advanced TLS certificate workflow for inspection
IA_internetAccessPoc — automated end-to-end Web Content Filtering POC setup

🔐 Authentication & Security

Entra ID (Azure AD) OAuth2 — full authentication for Microsoft Graph
Multiple auth modes — application (daemon) with client credentials, or delegated (user) via device-code flow
Token management — automatic refresh, secure caching, and expiry checking
MSAL integration — uses the Microsoft Authentication Library for Python
Non-blocking auth — background authentication keeps server startup fast
Secure storage — token cache written with restricted file permissions

Full setup: docs/authentication.md · Security policy: SECURITY.md

🚀 Getting Started

Prerequisites

Python 3.10+ and pip (or uv) — not needed if you use the standalone executable

Option 1 — Standalone executable (fastest)

No Python install required.

Windows: download getset-pox-mcp.exe from releases → create a .env (see .env.example) → run getset-pox-mcp.exe.

Linux/macOS: download getset-pox-mcp → chmod +x getset-pox-mcp → create .env → run ./getset-pox-mcp.

Build your own: BUILD_INSTRUCTIONS.md.

Option 2 — Install from source

git clone https://github.com/jeevanbisht/GetSetPOx.git
cd GetSetPOx

python -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate

pip install -e ".[dev]"

Option 3 — Using uv

uv venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"

Configuration for VS Code

Add the server to your VS Code settings.json or mcp.json.

STDIO mode (default)

{
  "mcp": {
    "servers": {
      "getset-pox-mcp": {
        "command": "python",
        "args": ["-m", "getset_pox_mcp.server"],
        "env": { "LOG_LEVEL": "INFO" }
      }
    }
  }
}

HTTP mode

{
  "mcp": {
    "servers": {
      "getset-pox-mcp": {
        "command": "python",
        "args": ["-m", "getset_pox_mcp.server"],
        "env": {
          "TRANSPORT": "http",
          "HTTP_HOST": "127.0.0.1",
          "HTTP_PORT": "3000",
          "HTTP_PATH": "/mcp",
          "LOG_LEVEL": "INFO"
        }
      }
    }
  }
}

⚙️ Configuration

Configure the server via environment variables (e.g. in a .env file).

Server

Variable	Description	Default	Example
`TRANSPORT`	Transport mode (`stdio` or `http`)	`stdio`	`http`
`HTTP_HOST`	HTTP host (HTTP mode)	`127.0.0.1`	`0.0.0.0`
`HTTP_PORT`	HTTP port (HTTP mode)	`3000`	`8080`
`HTTP_PATH`	HTTP endpoint path (HTTP mode)	`/mcp`	`/api/mcp`
`STATELESS_HTTP`	Use stateless HTTP mode	`false`	`true`
`LOG_LEVEL`	Logging level	`INFO`	`DEBUG`
`LOG_FILE`	Log file path	None	`logs/server.log`

Authentication (Entra ID)

Variable	Required	Default	Description
`ENTRA_ENABLE_AUTH`	No	`false`	Enable authentication
`ENTRA_TENANT_ID`	Yes*	–	Azure AD tenant ID
`ENTRA_CLIENT_ID`	Yes*	–	Application (client) ID
`ENTRA_CLIENT_SECRET`	Yes**	–	Client secret
`ENTRA_AUTH_MODE`	No	`application`	`application` or `delegated`
`ENTRA_SCOPES`	No	`https://graph.microsoft.com/.default`	Comma-separated scopes

* Required when authentication is enabled ** Required for application mode

Full instructions: docs/authentication.md.

🧪 Testing

pytest tests/                          # run the suite
pytest --cov=getset_pox_mcp tests/     # with coverage

🔧 Development

Project structure

GetSetPOx/
├── getset_pox_mcp/              # Main package
│   ├── server.py                # Server entry point + tool registration
│   ├── config.py                # Configuration management
│   ├── logging_config.py        # Logging setup
│   ├── authentication/          # OAuth2 provider, middleware, token manager
│   ├── transport/               # Transport layer implementations
│   └── services/                # MCP services and tools (one folder per domain)
│       ├── diagnostics/         # Graph permission diagnostics
│       ├── eid/                 # Entra ID management
│       ├── iga/                 # Identity Governance
│       ├── intune/              # Intune device management
│       ├── internetAccess/      # Global Secure Access — Internet Access
│       ├── poc/                 # POC orchestration utilities
│       └── Test/                # hello_world, echo
├── docs/authentication.md       # Auth setup guide
├── scripts/                     # setup.bat / setup.sh
├── tests/                       # Test suite
├── BUILD_INSTRUCTIONS.md        # PyInstaller build guide
├── ENV_PACKAGING_GUIDE.md       # Configuration packaging guide
├── getset-pox-mcp.spec          # PyInstaller spec
├── pyproject.toml               # Project configuration
├── CHANGELOG.md · CONTRIBUTING.md · CODE_OF_CONDUCT.md · SECURITY.md
└── LICENSE

Building a standalone executable

# Quick build (embeds .env)
prepare_env_for_build.bat        # Windows
./prepare_env_for_build.sh       # Linux/macOS

# Manual build
pip install pyinstaller
pyinstaller getset-pox-mcp.spec  # output in dist/ (~24 MB)

See BUILD_INSTRUCTIONS.md and ENV_PACKAGING_GUIDE.md.

Adding a new service

Create a tool in getset_pox_mcp/services/<domain>/:

from typing import Any

async def my_tool(param1: str, param2: int) -> dict[str, Any]:
    """Description of your tool.

    Args:
        param1: Description of param1
        param2: Description of param2

    Returns:
        Result dictionary
    """
    return {"result": "success"}

Register it in getset_pox_mcp/server.py:

from .services.<domain>.my_tools import my_tool

# In register_tools():
@mcp.tool()
async def my_tool_handler(param1: str, param2: int) -> dict[str, Any]:
    """Tool description"""
    return await my_tool(param1, param2)

Running in development

python -m getset_pox_mcp.server                 # STDIO transport
TRANSPORT=http python -m getset_pox_mcp.server  # HTTP transport

📋 Example Usage

Once configured, interact through any MCP-compatible client:

User:  Call the hello_world tool with name "Alice"
Agent: [calls hello_world]
Server: {"message": "Hello, Alice! Welcome to getset-pox-mcp."}

User:  Echo back "test message"
Agent: [calls echo]
Server: {
  "original": "test message",
  "echoed": "test message",
  "timestamp": "2025-01-16T19:40:00.000Z",
  "length": 12
}

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md and CODE_OF_CONDUCT.md.

Fork the repository and create a feature branch
Make your changes with appropriate tests
Ensure pytest passes
Submit a pull request

📄 License

MIT — see the LICENSE file for details.

🔗 Resources

📝 Changelog

See CHANGELOG.md for version history.

Name		Name	Last commit message	Last commit date
docs		docs
getset_pox_mcp		getset_pox_mcp
scripts		scripts
tests		tests
.editorconfig		.editorconfig
.env.example		.env.example
.gitignore		.gitignore
BUILD_INSTRUCTIONS.md		BUILD_INSTRUCTIONS.md
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
ENV_PACKAGING_GUIDE.md		ENV_PACKAGING_GUIDE.md
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
PROJECT_STRUCTURE.md		PROJECT_STRUCTURE.md
README.md		README.md
SECURITY.md		SECURITY.md
getset-pox-mcp.spec		getset-pox-mcp.spec
index.html		index.html
prepare_env_for_build.bat		prepare_env_for_build.bat
prepare_env_for_build.sh		prepare_env_for_build.sh
pyproject.toml		pyproject.toml
requirements-dev.txt		requirements-dev.txt
requirements.txt		requirements.txt
setup.py		setup.py

Latest commit

History

Folders and files

Repository files navigation