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

• 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
  

• 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
  

• 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:

• Navigate to Tools → AI & Agents (/settings/mcp) in psLens.
• Click Generate New Token.
• Choose a label (e.g. Google Antigravity, VS Code (MacBook)) and expiration period (30 days, 90 days, 1 year, or never).
• Configure token scoping rules:
  • Allowed Databases: Restrict access to specific databases (leave unselected for all databases).
  • Allow Production Access: Uncheck to restrict this token to non-production environments.
  • Read-Only Token: Check to block mutating operations (such as manage_alert_mute).
• 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

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"
      }
    }
  }
}

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.

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.

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 & Governance

The psLens MCP surface provides 20 specialized tools designed for efficient interaction with LLMs:

• Safe Tool Annotations: All inspection, audit, and triage tools include MCP annotations (readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false), which clients may use as hints to run queries without confirmation prompts.
• Database Resolution Policy: Every tool accepts db. If omitted and exactly one database is connected, it defaults to that database. When more than one database is connected, omitting db returns an error listing the available databases, preventing models from accidentally querying the wrong environment.
• Envelope Sizing: Multi-item queries default to summary projections; results larger than 80,000 characters are cut with an explicit [TRUNCATED by psLens ...] marker so clients do not reject the response.
• 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.
• Structured Data Filtering & PII Masking: query_table executes structured queries against whitelisted tables (CHG_PSLENS_WL) using typed operators (eq, ne, lt, le, gt, ge, like, in, is_null, not_null), date wrapping (%DateIn, %DateTimeIn), ordering, and limit/offset pagination. Passwords, hashes, and credential fields are stripped automatically, and sensitive PII columns are masked as *** based on the configurable mcp.maskedFields list.

Available Tools Catalog (20 Tools)

Metadata & Code Exploration (9 Tools)

Security & Access Auditing (4 Tools)

Operations & Sensor Health (5 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.
• data_migration_plan: Guided workflow for inspecting table schemas, row counts, and sequencing configuration data migrations across environments.

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: