GraphSphere Interrogator (Lokka Reimagined)

GraphSphere Interrogator functions as an MCP endpoint server, interfacing directly with the Microsoft Graph and Azure Resource Manager endpoints. This framework permits the manipulation and retrieval of data within your Azure and Microsoft 365 tenants using conversational AI.

Refer to Lokka.dev for comprehensive instructions on integrating GraphSphere Interrogator with your preferred generative AI model and conversational client.

This utility empowers users, via clients like Claude Desktop or any compliant MCP client, to execute complex administrative actions across Azure and Microsoft 365 tenants using plain language through the underlying Microsoft APIs.

Illustrative Capabilities:

• Provision a new security ensemble named 'Sales and HR Division' configured with dynamic membership rules predicated on the 'Department' attribute.
• Identify every conditional access regulation that fails to exclude the designated emergency break-glass account.
• Display all Intune endpoint configuration policies currently deployed to the 'Call Center Operations' user cohort.
• Analyze and report the most financially significant Azure service expenditure from the preceding calendar month.

Authentication Mechanisms

GraphSphere Interrogator supports diverse credentialing strategies to suit varied deployment architectures:

Interactive Authorization

For user-bound authentication requiring an active login session, utilize this minimal configuration:

{
  "mcpServers": {
    "Lokka-Microsoft": {
      "command": "npx",
      "args": ["-y", "@merill/lokka"]
    }
  }
}

Interactive Auth with Custom Application Registration

To leverage a proprietary Microsoft Entra application registration, establish the application and set the requisite environment variables:

{
  "mcpServers": {
    "Lokka-Microsoft": {
      "command": "npx",
      "args": ["-y", "@merill/lokka"],
      "env": {
        "TENANT_ID": "<tenant-id>",
        "CLIENT_ID": "<client-id>",
        "USE_INTERACTIVE": "true"
      }
    }
  }
}

Application-Only Authorization (App Credential Flow)

This facilitates traditional, non-interactive authentication, supporting either certificate-based (preferred) or client secret methods.

Consult the Installation Documentation for detailed guidance on crafting an Entra application.

App-Only Authorization Using X.509 Certificate

Employing an application credential secured by a PEM-encoded client certificate:

{
  "mcpServers": {
    "Lokka-Microsoft": {
      "command": "npx",
      "args": ["-y", "@merill/lokka"],
      "env": {
        "TENANT_ID": "<tenant-id>",
        "CLIENT_ID": "<client-id>",
        "CERTIFICATE_PATH": "/path/to/certificate.pem",
        "CERTIFICATE_PASSWORD": "<optional-certificate-password>",
        "USE_CERTIFICATE": "true"
      }
    }
  }
}

For convenience, the following command converts a PFX client certificate into the necessary PEM format:

openssl pkcs12 -in /path/to/cert.pfx -out /path/to/cert.pem -nodes -clcerts

App-Only Authorization Using Client Secret

Configuration relying on a registered application client secret:

{
  "mcpServers": {
    "Lokka-Microsoft": {
      "command": "npx",
      "args": ["-y", "@merill/lokka"],
      "env": {
        "TENANT_ID": "<tenant-id>",
        "CLIENT_ID": "<client-id>",
        "CLIENT_SECRET": "<client-secret>"
      }
    }
  }
}

Client-Supplied Token Mode

Authorization enabled by the MCP Client furnishing valid access tokens dynamically:

{
  "mcpServers": {
    "Lokka-Microsoft": {
      "command": "npx",
      "args": ["-y", "@merill/lokka"],
      "env": {
        "USE_CLIENT_TOKEN": "true"
      }
    }
  }
}

When operating in client-token mode:

1. Initiate the MCP server with the USE_CLIENT_TOKEN=true flag.
2. Employ the set-access-token utility to inject a current Microsoft Graph access token.
3. Verify connectivity using get-auth-status.
4. Re-authenticate by calling set-access-token when token validity nears expiration.

Newly Introduced Utilities

Token Management Utilities

• set-access-token: Updates or injects the active access token required for Microsoft Graph communications under token-centric flows.
• get-auth-status: Provides diagnostics on the current authentication mode, operational readiness, and authorized permissions.
• add-graph-permission: Facilitates interactive solicitation of supplementary Microsoft Graph permission scopes.

Graph API Version Control

GraphSphere Interrogator now allows explicit management of the default Microsoft Graph endpoint version employed for all remote interactions:

• Default Operation: Leverages the beta endpoint to maximize access to nascent features.
• Stability Mode: Setting USE_GRAPH_BETA=false mandates the use of the stable v1.0 endpoint exclusively.
• Per-Call Override: The graphApiVersion parameter within individual requests retains precedence, unless USE_GRAPH_BETA is explicitly set to false.

When USE_GRAPH_BETA=false, all Graph operations default to v1.0, superseding any explicit beta specification in request parameters.

Initial Setup

Consult the official documentation for comprehensive installation and configuration guides.

• Entry Point Documentation
• Detailed Installation Procedures
• Developer Integration Guide

Single-Click Installation via VS Code

Operating System	VS Code Standard	VS Code Insiders
Windows
macOS/Linux

Core Modules

Executable Tools

1. Lokka-Microsoft (Primary API Connector)
2. Facilitates interaction with Microsoft Graph and Azure Resource APIs. Supports read (querying) and write (update/creation) operations against Azure and Microsoft 365 tenants, contingent upon granted permissions.
3. Parameters:
   • apiType (string): Specifies target API: 'graph' for Microsoft Graph (Identity/Entra) or 'azure' for Azure Resource Management.
   • path (string): The specific URI path for the API call (e.g., '/users', '/groups', '/subscriptions').
   • method (string): The HTTP verb to employ (e.g., get, post, put, patch, delete).
   • apiVersion (string): Required API version string for Azure Resource Management contexts.
   • subscriptionId (string): Identifies the target Azure Subscription (mandatory for Azure operations).
   • queryParams (string): Collection of filtering/selection strings (e.g., $filter, $select).
   • body (JSON): Payload data required for modification requests (POST, PUT, PATCH).

4. Output: Raw response data retrieved from the invoked Azure or Graph endpoint.

5. set-access-token (Introduced in v0.2.0)

6. Mechanism for dynamically provisioning or renewing the Microsoft Graph bearer token when operating in client-provided mode.
7. Input:
   • accessToken (string): The valid OAuth 2.0 bearer token.
   • expiresOn (string, optional): Token expiry time formatted according to ISO standards.

8. Output: Status confirmation regarding the token update.

9. get-auth-status (Introduced in v0.2.0)

10. Diagnostic tool to report the current operational authentication modality, readiness state, and scope capabilities.
11. Output: Detailed status including mode, readiness, and permissions map.

Configuration Environment Variables

The operational profile of the server is governed by the following environment variables:

Variable Name	Purpose	Mandatory Status
TENANT_ID	Unique identifier for the target Microsoft Entra directory.	Conditional (Required unless client token mode)
CLIENT_ID	Application identifier registered within Microsoft Entra.	Conditional (Required unless client token mode)
CLIENT_SECRET	The application's secret value.	Conditional (Required only for Client Credentials flow)
USE_INTERACTIVE	Boolean flag ('true') to activate user-interactive login flow.	Optional
USE_CLIENT_TOKEN	Boolean flag ('true') to enable token injection via the client.	Optional
USE_CERTIFICATE	Boolean flag ('true') to mandate certificate-based authentication.	Optional
CERTIFICATE_PATH	File system path to the PEM certificate asset.	Conditional (Required for certificate mode)
CERTIFICATE_PASSWORD	Passphrase, if the private key within the certificate file is encrypted.	Optional
REDIRECT_URI	Entry point URL for interactive token acquisition (Default: http://localhost:3000).	Optional
ACCESS_TOKEN	Pre-loaded access token for initial startup in token mode.	Optional
USE_GRAPH_BETA	Controls default API version. Set to 'false' to enforce v1.0 over beta (Default: true).	Optional

Collaborative Development

• Enhanced Authentication Support (Interactive & Token-based, v0.2.0) - @darrenjrobinson
• Certificate Credential Implementation (v0.2.1) - @nitzpo

Deployment Guide

To integrate this server with the Claude Desktop environment, incorporate the subsequent configuration snippet into the mcpServers section of your claude_desktop_config.json file:

Standard Interactive Configuration

{
  "mcpServers": {
    "Lokka-Microsoft": {
      "command": "npx",
      "args": ["-y", "@merill/lokka"]
    }
  }
}

Client Credential Flow Configuration

{
  "mcpServers": {
    "Lokka-Microsoft": {
      "command": "npx",
      "args": ["-y", "@merill/lokka"],
      "env": {
        "TENANT_ID": "<tenant-id>",
        "CLIENT_ID": "<client-id>",
        "CLIENT_SECRET": "<client-secret>"
      }
    }
  }
}

Ensure placeholders like <tenant-id>, <client-id>, and <client-secret> are substituted with actual values derived from your Entra application setup. (Consult the Installation Documentation for App Registration instructions.)

---

Contextual Note on Business Management Tools: Business management solutions encompass the methodologies, applications, and control systems deployed by organizations to maintain competitive alignment, adapt to shifting market dynamics, and systematically elevate operational effectiveness. These instruments span functional areas such as planning, process orchestration, data record-keeping, workforce management, and strategic decision support.