Model Context Protocol (MCP) & Agent Skills

Embedded MCP Server

psLens includes an embedded Model Context Protocol (MCP) Server running directly inside the Go server process over Streamable HTTP and HTTP+SSE. It enables LLMs and coding assistants (such as Google Antigravity, VS Code, Claude Desktop, and Claude Code CLI) to inspect, analyze, triage, and compare PeopleSoft environments in real time with zero local daemon installation.

Agent Skills Distribution

psLens provides an embedded Agent Skill (pslens) package containing domain knowledge, PeopleSoft object naming rules, portable Meta-SQL syntax, effective-dating (EFFDT/EFFSEQ) join recipes, numeric status code mappings, and multi-step incident triage workflows.

Installation Options

1. Google Antigravity: Download and unpack the skill into your global Antigravity skills directory or workspace .agents/skills/:

   curl -sO https://{{yourorg}}.pslens.com/skills/pslens.zip
   unzip -o pslens.zip -d ~/.gemini/config/skills/
   rm pslens.zip
   

2. Claude Code / Agent Skill Download: Download the pre-packaged zip archive into Claude’s personal skills directory:

   curl -sO https://{{yourorg}}.pslens.com/skills/pslens.zip
   unzip -o pslens.zip -d ~/.claude/skills/
   rm pslens.zip
   

3. Skill Discovery Index: psLens implements the open Agent Skills Discovery specification (v0.2.0):

   GET /.well-known/agent-skills/index.json
   

Authentication & Personal Access Tokens

Access to the psLens MCP endpoints (/mcp and /mcp/sse) is secured via cryptographically generated Personal Access Tokens:

1. Navigate to Tools → AI & Agents (/settings/mcp) in psLens.
2. Click Generate New Token.
3. Choose a label (e.g. Google Antigravity, VS Code (MacBook)) and expiration period (30 days, 90 days, 1 year, or never).
4. Copy the raw secret key (psl_mcp_...). The secret is hashed with SHA-256 and stored in the internal NATS KV store; it is only displayed once upon generation.

Tokens can be passed to /mcp and /mcp/sse using:

• Authorization: Bearer psl_mcp_... header (recommended).
• X-API-Key: psl_mcp_... header.

Query-string tokens (?token=...) are not accepted: URLs end up in access logs and proxies, and the SSE transport’s endpoint event strips the query string, so query-based auth cannot survive the handshake anyway.

Operational Auditing & Activity Tracking

All MCP tool calls executed by connected AI clients are recorded to an embedded NATS JetStream Stream (mcp-audit) with automatic 30-day retention and a 500 MB disk storage cap.

Administrators can view recent operations, caller tokens, executed tools, target databases, execution durations, and error details directly in the Live MCP Operations Audit Log table at /settings/mcp.

Connecting Your AI Assistants

1. Google Antigravity

Add psLens to your global Antigravity configuration ~/.gemini/config/mcp_config.json or workspace configuration .gemini/mcp_config.json:

{
  "mcpServers": {
    "pslens": {
      "serverUrl": "https://{{yourorg}}.pslens.com/mcp",
      "headers": {
        "Authorization": "Bearer psl_mcp_YOUR_TOKEN_HERE"
      }
    }
  }
}

2. VS Code (GitHub Copilot)

Add psLens to your workspace configuration at .vscode/mcp.json. VS Code requires the top-level servers key (not mcpServers) and a type field, and connects over Streamable HTTP at /mcp:

{
  "servers": {
    "pslens": {
      "type": "http",
      "url": "https://{{yourorg}}.pslens.com/mcp",
      "headers": {
        "Authorization": "Bearer psl_mcp_YOUR_TOKEN_HERE"
      }
    }
  }
}

If .vscode/mcp.json is committed to a shared repository, use a VS Code inputs prompt variable instead of pasting the token inline:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "pslens-token",
      "description": "psLens MCP token",
      "password": true
    }
  ],
  "servers": {
    "pslens": {
      "type": "http",
      "url": "https://{{yourorg}}.pslens.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:pslens-token}"
      }
    }
  }
}

Extension-based MCP managers (Cline, Roo Code) use their own configuration with a top-level mcpServers key. For those, select transport SSE, set the endpoint to https://{{yourorg}}.pslens.com/mcp/sse, and add header Authorization: Bearer psl_mcp_YOUR_TOKEN_HERE.

3. Claude Desktop

Claude Desktop’s configuration file only supports local (stdio) servers — a url entry is silently ignored. Connect through the mcp-remote bridge instead (requires Node.js). Add to your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "pslens": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://{{yourorg}}.pslens.com/mcp",
        "--header",
        "Authorization: Bearer psl_mcp_YOUR_TOKEN_HERE"
      ]
    }
  }
}

Restart Claude Desktop after saving. Claude Desktop’s Settings → Connectors can add a remote server by URL, but it cannot send a bearer token header, so the bridge is required for psLens tokens.

4. Claude Code CLI

Add psLens with a single command in your terminal:

claude mcp add --transport http pslens https://{{yourorg}}.pslens.com/mcp --header "Authorization: Bearer psl_mcp_YOUR_TOKEN_HERE"

Architecture & Sizing Contracts

The psLens MCP surface is structured into 20 tools (18 domain tools + 2 developer tools) with strict payload sizing contracts:

• Safe Tool Annotations: All inspection, audit, and triage tools include MCP annotations (readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false), eliminating permission popups in Claude Desktop and Cursor.
• Envelope Sizing Tiering:
  • Summary: Small token footprints (~200 tokens) for exploration and high-volume operations.
  • Structured: Medium token footprints (~1,500 tokens) for focused object inspection.
  • Full: Markdown / detailed responses (~4,000 tokens) when complete field or code context is required.
• Self-Describing Numeric Enums: Payloads automatically include human-readable enum decoders (FieldTypeDesc, FormatDesc, RecTypeDesc, RunStatusDesc) alongside PeopleTools integer constants.
• Subrecord Expansion: get_record_schema and batch_records_summary flatten nested subrecords by default into an effective field list.
• Batch Record Introspection: batch_records_summary resolves up to 25 record schemas in parallel in a single round trip, avoiding multi-turn join query loops.
• Credential Protection: get_table_sample_and_count automatically strips sensitive password, hash, and token columns from table row samples.
• Client-Safe Output Size: Results larger than 80,000 characters are cut with an explicit [TRUNCATED by psLens ...] marker so the client does not reject the response.

Available Tools Catalog (20 Tools)

🔍 Metadata & Code Exploration (10 Tools)

🛡️ Security & Access Auditing (4 Tools)

⚡ Operations & Sensor Health (4 Tools)

🔄 Comparison & Reports (2 Tools)

Passive Resources

Agents can passively subscribe to or read structured context feeds:

• pslens://databases: Configured PeopleSoft databases, connection health, and production status.
• pslens://catalog/object-types: Catalog of supported PeopleSoft metadata families and search conventions.
• pslens://env/summary: Real-time summary of connected environments and active alert counts.
• pslens://alerts/active: Live list of all currently firing alert incidents across all monitored environments.
• pslens://system/health/{db}: Real-time health sensor telemetry, Process Scheduler status, and IB health for the specified database.
• pslens://whitelist/{db}: Whitelisted tables allowed for SWS introspection in a given database.

Workflow Prompts

The MCP server exposes guided multi-step prompts for incident response, development, and proactive monitoring:

• proactive_system_monitor: Autonomous monitoring agent sequence inspecting system health telemetry, Process Scheduler status, Integration Broker status, and active alerts.
• post_migration_verification: Runs object difference verification, recurrence consistency checks, and IB routing health tests after a project migration.
• incident_triage: Automated diagnostic sequence for on-call administrators during production alerts or performance spikes.
• user_security_audit: Deep-dive security audit for a specific user ID.
• impact_analysis: Calculates upstream and downstream blast radius before modifying a record, field, or component.
• security_compliance_audit: Environment-wide security compliance audit inspecting dangerous grants, full-access permission lists, and SOAP-to-CI endpoints.
• event_mapping_impact_analysis: Custom Event Mapping business logic analysis and injected Application Class review before PUM image upgrades.
• dms_migration_generator: Guided workflow for generating, linting, and validating Data Mover export/import scripts.

PeopleTools 8.63 Native MCP vs. psLens MCP

PeopleTools 8.63 introduces native Model Context Protocol (MCP) server support directly into the PeopleSoft platform. While both implementations use the open MCP standard, they serve different layers and operational needs: