# Model Context Protocol (MCP) & Agent Skills > Embedded Model Context Protocol server and Agent Skills for connecting Google Antigravity, VS Code, Claude Code, and Claude Desktop directly to PeopleSoft intelligence. --- Site [llms.txt](/llms.txt) --- ## 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/`: ```bash 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: ```bash 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): ```text 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`: ```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`: ```json { "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: ```json { "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` ```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: ```bash 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) | Tool | Purpose | Sizing Tier | | :---------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------- | | `search_objects` | Search across supported PeopleSoft object families (`record`, `field`, `page`, `component`, `menu`, `apppackage`, `appengine`, `sqlobject`, `query`, `project`, `ci`, `serviceop`, `user`, `role`, `permissionlist`, `msgcat`, `all`) | Summary | | `search_code_sql` | Targeted search across PeopleCode programs, SQL Objects, and App Engine statements | Full | | `get_record_schema` | Structure, fields, keys, prompt table pointers, DDL parameters (`format='ddl'`), or formatted markdown (`format='markdown'`) | Structured / Full | | `batch_records_summary` | Inspect schemas, keys, and prompt tables for up to 25 records in one call | Structured | | `get_definition` | PeopleTools metadata definitions in formatted markdown across 30 object types (`record`, `field`, `page`, `component`, `menu`, `apppackage`, `appengine`, `sqlobject`, `query`, `project`, `ci`, `serviceop`, `user`, `role`, `permissionlist`, `node`, `queue`, `message`, `processdefinition`, `processjob`, `recurrence`, `url`, `filelayout`, `serverdefn`, `service`, `bipublisher`, `html`, `style`, `cref`, `portal`, `search`, `eventmap`, `querytree`) with optional `sections` filtering | Structured / Full | | `get_peoplecode` | Source text from any container (`record_field`, `component`, `app_package`, `app_engine`, `page`, `ci`) with line paging (`start_line`, `max_lines`) | Full | | `find_dependencies` | Reverse where-used dependencies, blast radius, and impact paths for fields, records, components, or pages | Structured | | `analyze_record_field_impact` | Focused blast radius evaluation for a specific `RECORD.FIELD` across pages, components, CIs, PeopleCode, queries, and file layouts | Structured | | `query_table` | Structured table query with typed filters (`eq`, `ne`, `lt`, `le`, `gt`, `ge`, `like`, `in`, `is_null`, `not_null`), ordering, limit/offset paging, and row counts; credential fields excluded and sensitive PII masked (`***`) | Structured | ### Security & Access Auditing (4 Tools) | Tool | Purpose | Sizing Tier | | :--------------------- | :--------------------------------------------------------------------------------------------------------------- | :------------------- | | `who_has_access` | Backward security traversal for components, service operations, query trees, permission lists, or roles | Structured | | `user_access_summary` | Security profile for an OPRID including roles, permission lists, lock status, and elevated dangerous permissions | Summary / Structured | | `user_login_audit` | Inspect recent login history and failed authentication attempts from `PSPTLOGINAUDIT` | Structured | | `audit_security_risks` | Automated scans for elevated privileges, full-access permission lists, and SOAP-to-CI endpoints | Full | ### Operations & Sensor Health (5 Tools) | Tool | Purpose | Sizing Tier | | :------------------ | :--------------------------------------------------------------------------------------------------- | :------------------------ | | `list_databases` | Discover configured PeopleSoft databases, connection status, production flags, and PIA URLs | Summary | | `get_system_health` | Sensor health telemetry (heartbeats, IB domains, down nodes, stalled jobs, active firing alerts) | Summary / Full (Markdown) | | `triage_operations` | Triage Process Scheduler batch errors, backlogged queues, locked-OPRIDs, and IB contract errors | Structured | | `get_alerts` | Currently firing alert incidents or background checker history (`view="active"` or `view="history"`) | Summary / Structured | | `manage_alert_mute` | Manage alert silencing/mute rules (list, create silence for up to 7 days, delete by rule ID) | Summary | ### Comparison & Reports (2 Tools) | Tool | Purpose | Sizing Tier | | :--------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------- | | `compare_environments` | Cross-environment drift comparison (`compare_type='project'`, `'missing_projects'`, `'recurrences'`, `'object'` with `object_type='record'|'peoplecode'|'role'|'permissionlist'|'user'`) | Structured / Full | | `run_report` | Run any built-in psLens security, IB, or batch audit report on demand with markdown findings | Full | --- ## 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: | Capability | PeopleTools 8.63 Native MCP | psLens Embedded MCP Server | | :------------------------------- | :--------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Target Audience** | End users, functional analysts, developers in App Designer | Administrators, DBAs, Developers, Security Auditors, SREs | | **PeopleTools Version** | Requires **PeopleTools 8.63+** exclusively | **Version Agnostic**: PeopleTools 8.53 through 8.63+ | | **Environment Scope** | **Single-database bounded**: Queries only the hosted 8.63 instance | **Multi-environment orchestration**: Simultaneously queries and compares `DEV`, `TEST`, and `PROD` in one session | | **Core Focus** | • Natural Language Search (OpenSearch)
• Transactional Application Services
• App Designer AI Assist | • Deep Metadata Introspection (subrecord flattening, page buffers, components, App Engines, SQL Objects)
• Reverse Where-Used Dependency Graph
• PeopleCode extraction across all container types
• Security Graph & Access Auditing (reverse component access, dangerous permissions, login audit)
• Operational Triage (Process Scheduler queues, locked OPRIDs, IB exceptions, live alerts)
• Cross-Environment Migration & Project Drift Auditing | | **Cross-Environment Drift** | Not supported natively across environments | Built-in via `compare_environments` (`project`, `object`, `recurrences`, `missing_projects`) | | **Infrastructure Prerequisites** | Full PT 8.63 stack (WebLogic PIA, Tuxedo App Server, OpenSearch) | Standalone Go service connecting via Simple Web Services (SWS) with database whitelisting (`CHG_PSLENS_WL`) | | **Agent Optimizations** | Standard PeopleSoft JSON payloads | Human-readable enum decoders (`FieldTypeDesc`, `RunStatusDesc`), password column exclusion, PII masking, safe read-only tool annotations, batch record introspection |