Skip to main content
Glama
thetechnicalsavage

wls-mcp

by thetechnicalsavage
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

wls-mcp

An MCP server that exposes a small, audited slice of the Oracle WebLogic Server REST management API to an AI agent — four tools, a least-privilege service account, and a JSON audit record for every call.

Built and verified against WebLogic Server 15.1.1.0 (Generic, JDK 21, Oracle Linux 9) running in Docker.

Why WebLogic, why now

Oracle removed the browser-based WebLogic Administration Console in 14.1.2, and 15.1.1 ships without it. Day-to-day administration is REST, WLST, or the separate WebLogic Remote Console. That makes WebLogic a natural fit for MCP: the management surface is already an HTTP API, so this server is a thin, explicit wrapper rather than screen-scraping — and the interesting work is in scoping and auditing it, not in plumbing.

Related MCP server: WLST MCP Server

Tools

Tool

Reads

Notes

list_servers

serverLifeCycleRuntimes + edit/servers

Every configured server with state, port, machine. The only view that includes stopped servers.

get_server_health

serverRuntimes/{name}

Health state, failed subsystem, symptoms. Returns lifecycle state instead when the server is not RUNNING.

get_jvm_stats

serverRuntimes/{name}/JVMRuntime

Heap current/max/free, free %, uptime, Java version. Bytes converted to MB.

control_server

serverLifeCycleRuntimes/{name}/{action}

start, shutdown, force_shutdown, via Node Manager. Destructive; see guardrails.

Three WebLogic behaviours the tool contracts are built around:

  1. serverRuntimes only contains RUNNING servers. A stopped server is absent entirely — not present with state: SHUTDOWN. So listing servers must read serverLifeCycleRuntimes, while health and JVM stats read serverRuntimes.

  2. serverRuntimes can be briefly empty while a managed server registers with the domain runtime service. "No runtime record" means not currently running, not error.

  3. X-Requested-By is mandatory on state-changing requests; WebLogic rejects them as CSRF otherwise. The header value is arbitrary — its presence is the point.

Guardrails

control_server is the only tool that changes anything, and it is fenced:

  • Least-privilege account. The server authenticates as a dedicated WebLogic user in the Operators and Monitors groups — never the domain administrator. That account can read runtime state and drive server lifecycle, and is refused when it tries to open a configuration edit session or create resources (verified: 403 on both).

  • Allowlist. WLS_ALLOWED_SERVERS restricts which servers are addressable at all. Unset means the whole domain.

  • Read-only mode. WLS_READ_ONLY=true disables control_server outright.

  • Administration Server confirmation. Stopping the AdminServer also stops the REST API this server depends on, so nothing here can start it again. It requires confirm=true, and the response carries the host-level recovery command. WLS_ALLOW_ADMIN_SHUTDOWN=false forbids it entirely.

  • No retry on lifecycle calls. GETs retry with capped exponential backoff; start and shutdown are sent exactly once.

Audit trail

Every invocation emits exactly one JSON record, on success, refusal, or error:

{"ts":"2026-09-13T12:41:07.882Z","tool":"control_server","principal":"wlsmcp",
 "target":"ms1","arguments":{"server_name":"ms1","action":"shutdown","confirm":false},
 "outcome":"success","duration_ms":9183}

Records go to stderr, and to WLS_AUDIT_LOG as JSON Lines if set. Nothing is ever written to stdout — under the stdio transport, stdout is the MCP protocol channel, and a stray print corrupts the session.

Install

uv venv && uv pip install -e .
cp .env.example .env   # then fill in WLS_PASSWORD

Run

Stdio, for a local client:

wls-mcp

Streamable HTTP, to serve a client on another machine:

wls-mcp --transport streamable-http --host 0.0.0.0 --port 8765

Over HTTP the server has no authentication of its own — put it behind a reverse proxy that terminates TLS and checks a bearer token, or keep it on a private network.

Wiring it into a client

Codex CLI

codex mcp add weblogic \
  --env WLS_BASE_URL=http://localhost:7001 \
  --env WLS_USERNAME=wlsmcp \
  --env WLS_PASSWORD=... \
  -- /path/to/.venv/bin/wls-mcp

or over HTTP:

codex mcp add weblogic --url http://host:8765/mcp --bearer-token-env-var WLS_MCP_TOKEN

Claude Code

claude mcp add weblogic --env WLS_USERNAME=wlsmcp --env WLS_PASSWORD=... -- /path/to/.venv/bin/wls-mcp

Configuration

See .env.example. Credentials are read only from the environment, never from argv, so they do not show up in ps.

Tests

uv pip install -e ".[dev]" && pytest

Unit tests mock the WebLogic REST API with respx; no live server needed.

Licence

MIT. The Oracle WebLogic Server binaries are not included or redistributed here — you pull Oracle's image yourself after accepting the licence on Oracle Container Registry. See ../RUNBOOK.md for the full domain build.

Available Tools

4 tools
control_serverA
Destructive

Start or stop a WebLogic server through Node Manager. action is one of: 'start', 'shutdown' (graceful), 'force_shutdown' (immediate, use to clear a wedged server). Stopping the Administration Server also stops the REST API this tool depends on, so it requires confirm=true and cannot be undone through this tool. If this server is configured with a break-glass token, every action additionally requires that token, which only a human operator can provide - never guess it.

ParametersJSON Schema
NameRequiredDescriptionDefault
tokenNo
actionYes
confirmNo
server_nameYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true and non-idempotent, but the description goes well beyond: it explains that stopping the Admin Server kills the REST API this very tool depends on, that the action cannot be undone through this tool, and that a break-glass token may be required with a strong 'never guess it' warning. This is rich, safety-critical context not derivable from annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tight, front-loaded prose: verb/resource first, then action semantics, then the destructive confirm scenario, then the token caveat. No filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, but given the mutation and risk profile the description covers the decision-critical facts: action choices, irreversibility, required confirmation, and conditional human-supplied token. An agent has everything needed to choose and invoke safely.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must carry parameter meaning. It defines the valid action values with nuance, ties confirm to the Admin Server shutdown case, and explains the token's human-operator origin. server_name is unsurprisingly self-evident, and defaults are visible in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Title and description state a specific verb (start/stop) and resource (WebLogic server via Node Manager), clearly distinguishing it from read-only siblings like list_servers and get_server_health.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly describes each action mode and when to use each – 'force_shutdown' is called out as the remedy for a wedged server, and the shutdown-of-Administration-Server scenario is flagged with its required confirm and irreversibility.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_jvm_statsA
Read-only

Return JVM heap and runtime statistics for one RUNNING WebLogic server: current and maximum heap, free heap and free percentage, uptime, and the Java version in use. Byte values are also given in MB for readability.

ParametersJSON Schema
NameRequiredDescriptionDefault
server_nameYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, so the safety profile is covered; the description adds useful behavioral context beyond that: the target must be a RUNNING server, and byte values are converted to MB for readability. It does not discuss permissions or failure modes, but for a read-only stats call the added context is substantive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence listing the returned metrics followed by a brief unit note; no filler, no repetition of the tool name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return shape need not be explained, yet the description helpfully summarizes it. The only residual gap is explicit routing versus siblings like get_server_health; otherwise an agent has everything needed to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is one parameter, server_name, at 0% schema description coverage. The description's reference to 'one RUNNING WebLogic server' implies the parameter identifies the server, but it adds no format or naming guidance (e.g., logical vs instance name). Adequate but thin compensation for the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (return JVM heap and runtime statistics) and enumerates exactly which values come back: current/max heap, free heap and percentage, uptime, Java version. The 'one RUNNING WebLogic server' scoping distinguishes it from get_server_health and list_servers without needing the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'for one RUNNING WebLogic server' implies a precondition (the server must be running) and the single-server granularity suggests usage context, but no sibling tool is named and there is no explicit when-to-use-this-vs-get_server_health guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_server_healthA
Read-only

Report the health of one WebLogic server: overall health state (ok, warn, critical, failed, overloaded), the subsystem at fault if any, and reported symptoms. A server that is not RUNNING has no health data; its lifecycle state is returned instead.

ParametersJSON Schema
NameRequiredDescriptionDefault
server_nameYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.8/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already establish readOnlyHint=true, so the safety profile is covered. The description adds genuine non-obvious behavior: servers that are not RUNNING have no health data and return lifecycle state instead, which is exactly the edge case an agent needs. It stops short of describing freshness, auth, or error behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences, no filler, with the core purpose front-loaded and the important edge case (non-RUNNING servers) placed last as a caveat.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be spelled out, yet the description usefully enumerates the health states and explains the non-RUNNING fallback. It omits what happens for an unknown server name, but for a one-parameter read tool this is close to complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter server_name has 0% schema description coverage, so the description must compensate. It only implies that one identifiable server is targeted ('one WebLogic server'); it adds no naming convention, case sensitivity, or domain/path format guidance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb ('Report') and resource ('health of one WebLogic server') and enumerates the returned health states (ok, warn, critical, failed, overloaded), so the operation is unambiguous. It does not name or contrast with siblings like get_jvm_stats or list_servers, leaving differentiation to be inferred from the resource.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: an agent can infer you call this to inspect a single server's health. There is no explicit when-to-use vs when-not-to-use, and no alternatives (e.g., list_servers for enumeration, get_jvm_stats for deeper diagnostics) are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_serversA
Read-only

List every configured server in the WebLogic domain with its current lifecycle state (RUNNING, SHUTDOWN, STARTING, FAILED_NOT_RESTARTABLE, ...), listen port and assigned machine. This is the only view that includes stopped servers.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=true, so safety is covered. The description adds real behavioral value by enumerating the lifecycle state values (RUNNING, SHUTDOWN, STARTING, FAILED_NOT_RESTARTABLE, ...) and clarifying that stopped servers are included — a non-obvious inclusion that an agent could otherwise miss.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences, front-loaded with the primary action and resource, followed by a differentiating scope claim. No filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Output schema exists, so return structure needn't be explained; the description still helpfully names key fields and the STOPPED-inclusion behavior. Covers what an agent needs to call it correctly for a 0-param tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters, so the baseline is 4. The description correctly implies a no-argument, full-domain listing, adding meaning about scope beyond the empty schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (List) and resource (every configured server in the WebLogic domain) with the exact fields returned (lifecycle state, listen port, machine). The distinguishing claim 'the only view that includes stopped servers' cleanly separates it from siblings like get_server_health and get_jvm_stats.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states the condition that selects this tool over alternatives: it is the only view that includes stopped servers. An agent knows to use it when it needs a full inventory rather than live metrics or health.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv1.0.0
    • First observedcontrol_server
    • First observedget_jvm_stats
    • First observedget_server_health
    • First observedlist_servers
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.2/5.0

Scored across 4 tools

Disambiguation4/5

The four tools target distinct facets—inventory, health, JVM metrics, and lifecycle control—so selection is generally clear. The only minor overlap is lifecycle state information appearing in both list_servers and get_server_health for non-running servers, but descriptions clarify when to use each.

Naming Consistency5/5

All names use snake_case with a verb-first pattern (list_*, get_*, control_*), and the two get_* tools are parallel. No camelCase or inconsistent verb styles.

Tool Count5/5

Four tools is a tight, focused surface for a WebLogic server-management MCP; each tool covers a distinct need (list, health, JVM stats, control). This sits comfortably in the well-scoped 3–15 range.

Completeness4/5

Core server lifecycle and observability are covered: inventory, health, JVM, and start/stop. Minor gaps exist—no dedicated restart, logs, thread dumps, or configuration inspection—but these are not fatal for the stated server-control purpose.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Oracle Database MCP Server

    tannerpace
    A
    license
    A
    quality
    A
    maintenance
    Enables GitHub Copilot and other LLMs to execute read-only SQL queries against Oracle databases with secure connection pooling and schema introspection capabilities.
    2
    105 npm
    5
    AGPL 3.0

  • WLST MCP Server

    rcarrascosps
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables management of Oracle WebLogic Server domains using WLST, including server lifecycle, application deployment, monitoring, and diagnostics.
    2
    Apache 2.0

  • sec-ops-mcp

    JoaquinHernandez
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables LLMs and AI agents to perform defensive security posture assessments, privilege escalation surface audits, and post-quantum cryptography readiness checks through read-only diagnostic tools.
    MIT

  • Kalymos Hoag

    GustavoVieiraDeAraujo
    F
    license
    Not graded
    quality
    C
    maintenance
    Enables AI agents to audit server health and operations through read-only tools, including container status, logs, alerts, and WhatsApp session status, without requiring SSH access.
    -