Skip to content
SparkyaiPeopleSoft

Get and configure the server

This page gets the server ready to run on your machine: the image, the database password, the settings, and a check that everything works. The commands use Podman; the Docker notes at the end cover the differences.

Get the image

Section titled “Get the image”

Your administrator provides the AI Assist image, either in your organization’s container registry or as a file. Load it, and make sure it’s tagged aipeoplesoft-mcp:1.0, the name these pages use:

Terminal window
podman pull <your-registry>/aipeoplesoft-mcp:1.0
podman tag <your-registry>/aipeoplesoft-mcp:1.0 aipeoplesoft-mcp:1.0

Store the database password

Section titled “Store the database password”

Store the password of the database account once, as a Podman secret. Every IDE then refers to the secret by name, so the password never appears in a configuration file, a command line, or your shell history:

Terminal window
$env:AIPS_DB_PASSWORD = [System.Net.NetworkCredential]::new(
  '', (Read-Host -AsSecureString 'Database password')).Password
podman secret create --env=true aips_db_password AIPS_DB_PASSWORD
Remove-Item Env:AIPS_DB_PASSWORD

The prompt hides what you type, and --env=true reads the secret from the temporary environment variable, which is removed straight afterward. To change the password later, remove the secret with podman secret rm aips_db_password and create it again.

Configure the server

Section titled “Configure the server”

For a local setup, environment variables are all the configuration the server needs:

Variable Required Description
AIPS_DB_PLATFORM Yes oracle or sqlserver
AIPS_DB_CONNECT Yes host:port/name, where name is the Oracle service name or the SQL Server database, such as hrdb.example.com:1521/HRDEV
AIPS_DB_USER Yes The database account, such as AIPS_MCP
AIPS_DB_PASSWORD Yes Its password, supplied by the Podman secret
AIPS_DB_PASSWORD_FILE No A file inside the container that holds the password, as an alternative to AIPS_DB_PASSWORD
AIPS_DB_SCHEMA No The owner of the PeopleSoft tables. Default: SYSADM on Oracle Database, dbo on SQL Server
AIPS_CONFIG No A configuration file inside the container. Default: /etc/aipeoplesoft/config.yaml, if it exists
AIPS_USER No The name the audit log records as the user. Default: local

Everything else has a default. To change a default, such as the query timeout or the run_select allow-list, use a configuration file.

The configuration file

Section titled “The configuration file”

The configuration file is YAML. A value written as ${NAME} is read from an environment variable, so the file never needs to contain the password, and environment variables override the file. This example shows every setting with its default:

config.yaml
database:
  platform: oracle            # oracle or sqlserver
  connect: hrdb.example.com:1521/HRDEV
  user: AIPS_MCP
  password: ${AIPS_DB_PASSWORD}
  schema: SYSADM              # SYSADM on Oracle, dbo on SQL Server
  pool_size: 4


server:
  transport: stdio            # stdio or http
  instructions: >-
    Read-only access to PeopleTools metadata in the HRDEV
    database. Custom definitions start with ZZ_.


limits:
  query_timeout_seconds: 30
  calls_per_minute: 60        # per user
  max_peoplecode_lines: 2000
  max_app_engine_steps: 500


search:
  portal: EMPLOYEE


run_select:
  enabled: false
  allowed_tables: []
  sensitive_columns: []
  max_rows: 1000


audit:
  destination: stderr         # stderr, or a file path

The server’s instructions reach the LLM through discovery. Use them to name the database and explain your conventions, such as the prefix of your custom definitions. HTTP-only settings for a shared server are covered in Run a shared server.

To use the file, mount it into the container at its default path by adding this option to podman run:

Terminal window
-v ./config.yaml:/etc/aipeoplesoft/config.yaml:ro

On Linux hosts that use SELinux, add ,Z after ro so the container is allowed to read the file.

Check the setup

Section titled “Check the setup”

The image has a check command that tests the connection and the account’s access, without starting the MCP server. Run it with the same settings your IDE will use:

Terminal window
podman run --rm `
  -e AIPS_DB_PLATFORM=oracle `
  -e AIPS_DB_CONNECT=hrdb.example.com:1521/HRDEV `
  -e AIPS_DB_USER=AIPS_MCP `
  --secret aips_db_password,type=env,target=AIPS_DB_PASSWORD `
  aipeoplesoft-mcp:1.0 check

A healthy setup looks like this:

Output of check
aipeoplesoft-mcp 1.0.0
Database      Oracle Database, connected as AIPS_MCP
PeopleTools   8.62 (from PSSTATUS.TOOLSREL)
Tables        28 of 28 readable
Privileges    READ only
run_select    disabled
Result        ready

check reads the account’s privileges from the database’s own catalog; it never tries to write. It stops with an error when:

  • It can’t connect. The error includes the database’s own message, such as ORA-01017 (invalid user name or password) or ORA-12541 (no listener) on Oracle Database, or error 18456 (login failed) on SQL Server.
  • A table isn’t readable. It lists the missing grants, or suggests AIPS_DB_SCHEMA if the tables belong to a different owner. The optional tables, PSROLEUSER, PSQRYRECORD, and PSQRYFIELD, produce a warning instead.
  • The account can do more than read. Any privilege beyond read access is reported as an error, because the account should be read-only. On Oracle Database, SELECT grants produce a warning: they allow reading, but also locking rows, so grant READ instead.

Using Docker

Section titled “Using Docker”

Every command on these pages also works with docker in place of podman, except for secrets: docker run has no --secret option. With Docker, supply the password through the environment instead. Set AIPS_DB_PASSWORD in the environment your IDE starts the container from, and pass it through by name with -e AIPS_DB_PASSWORD, in place of the --secret option. VS Code and Cursor can fill in that variable for you; Connect your IDE shows how.