Skip to main content
Glama
nhkm95

AWS Infrastructure Operations MCP

by nhkm95
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

AWS Infrastructure Operations MCP

A local, read-only MCP server that allows an AI client such as Codex to investigate an AWS EC2 workload using controlled, live evidence.

The server can inspect EC2 health, CloudWatch metrics, CloudWatch logs, nginx service state, the nginx system journal, and recent CloudTrail activity. It does not expose a general-purpose shell or any remediation capabilities.

What this project demonstrates

This project combines:

  • Model Context Protocol (MCP)

  • Python and FastMCP

  • AWS SDK for Python (Boto3)

  • Amazon EC2

  • Amazon CloudWatch Metrics

  • Amazon CloudWatch Logs Insights

  • AWS Systems Manager

  • AWS CloudTrail

  • AWS IAM and STS

  • Terraform

  • Least-privilege infrastructure diagnostics

The current implementation supports one approved lab instance named web01 and one approved service named nginx.

Related MCP server: masaro-infra-mcp

Architecture

flowchart LR
    User["Engineer"] --> Codex["Codex MCP host"]
    Codex --> MCP["Local Python MCP server"]

    MCP --> Guard["AWS runtime identity guard"]
    Guard --> STS["AWS STS"]

    MCP --> EC2["Amazon EC2"]
    MCP --> Metrics["CloudWatch Metrics"]
    MCP --> Logs["CloudWatch Logs"]
    MCP --> SSM["AWS Systems Manager"]
    MCP --> Trail["AWS CloudTrail"]

    SSM --> Web01["EC2: web01"]

Codex starts the MCP server as a local process and communicates with it over standard input and output.

The MCP server:

  1. Validates its AWS account and assumed role.

  2. Validates the requested instance, service, time range, and result limit.

  3. Calls only approved AWS APIs.

  4. Returns a limited structured result with its data source.

  5. Does not perform remediation.

MCP tools

The server exposes six live AWS-backed tools.

Tool

Purpose

Data source

get_instance_health

Returns EC2 state and AWS system and instance status checks

aws

get_instance_metrics

Returns fixed EC2 CPU, status-check, and network metrics

aws-cloudwatch-metrics

get_recent_errors

Searches approved CloudWatch log groups for recent errors

aws-cloudwatch

get_recent_changes

Returns bounded CloudTrail activity associated with the instance

aws-cloudtrail-event-history

get_service_status

Returns the current nginx systemd state through a fixed SSM document

aws-ssm

get_service_journal

Returns a bounded nginx system journal through a fixed SSM document

aws-ssm-journal

get_instance_health

instance_name: str

Current restrictions:

  • instance_name must be web01.

  • Callers cannot supply an EC2 instance ID.

  • Instance resolution requires the approved EC2 name and access tags.

The response includes:

  • Instance ID

  • AWS Region

  • Availability Zone

  • Private IP address

  • EC2 state

  • System status

  • Instance status

  • Check timestamp

get_instance_metrics

instance_name: str
minutes: int = 60

Current restrictions:

  • instance_name must be web01.

  • minutes must be between 5 and 1,440.

  • The caller cannot supply a metric namespace, dimension, statistic, period, or CloudWatch query.

The tool retrieves a fixed set of AWS/EC2 metrics:

  • CPUUtilization

  • StatusCheckFailed

  • StatusCheckFailed_Instance

  • StatusCheckFailed_System

  • NetworkIn

  • NetworkOut

Missing datapoints are returned as null rather than being represented as zero.

get_recent_errors

instance_name: str
maximum_results: int = 10
minutes: int = 60

Current restrictions:

  • instance_name must be web01.

  • maximum_results must be between 1 and 50.

  • minutes must be between 5 and 1,440.

  • Callers cannot provide Logs Insights query text or log-group names.

The server queries only:

/aws/mcp-lab/web01/system
/aws/mcp-lab/web01/nginx

An empty result means that no matching events were returned within the requested window. It does not prove that the application is reachable or healthy.

get_recent_changes

instance_name: str
hours: int = 24
maximum_results: int = 25

Allowed lookback values:

1, 6, 12, 24, 48, 72, 168 hours

Allowed result limits:

10, 25, 50

The tool searches a fixed server-side allowlist of relevant EC2 and Systems Manager events. It then verifies that each event explicitly references the approved instance ID.

Returned event information is deliberately limited to:

  • Event time

  • Event name

  • Event source

  • Compact actor attribution

  • CloudTrail read-only indicator

  • Instance-matching method

The tool does not return raw CloudTrail JSON, credentials, request headers, source IP addresses, user-agent strings, or complete session context.

CloudTrail Event History is eventually consistent. Very recent API activity may take several minutes to appear.

get_service_status

instance_name: str
service_name: str

Current restrictions:

  • instance_name must be web01.

  • service_name must be nginx.

  • The caller cannot provide a command, document name, path, instance ID, or shell argument.

The tool invokes only the Terraform-managed SSM document:

mcp-lab-get-nginx-status

The document runs a fixed set of read-only systemctl checks and returns:

  • Active state

  • Sub-state

  • Whether nginx is enabled at boot

  • Command status

  • Check timestamp

get_service_journal

instance_name: str
service_name: str
minutes: int = 60
maximum_results: int = 50

Allowed lookback values:

5, 10, 15, 30, 60, 120 minutes

Allowed result limits:

10, 25, 50, 100

The tool invokes only:

mcp-lab-get-nginx-journal

The document fixes the systemd unit to nginx and executes a bounded, read-only journal query.

The SSM document internally uses the aws:runShellScript document plugin to execute its fixed command. This is not the same as allowing the MCP runtime to invoke the unrestricted AWS-managed AWS-RunShellScript document.

Security boundaries

The project follows a defence-in-depth model.

Dedicated runtime role

The MCP server uses a dedicated role:

aws-infra-ops-mcp-lab-runtime

This is separate from:

  • The Terraform administrator or source identity

  • The EC2 instance profile

  • The user’s interactive AWS identity

The runtime role receives only the permissions required by the approved diagnostic tools.

Fail-closed identity guard

Before an AWS-backed tool creates its service client, the server calls AWS STS and validates:

  • The expected AWS account

  • The exact assumed-role name

  • The expected STS assumed-role ARN structure

Required environment variables:

MCP_EXPECTED_AWS_ACCOUNT_ID
MCP_EXPECTED_AWS_ROLE_NAME

The server accepts an identity shaped like:

arn:aws:sts::<AWS_ACCOUNT_ID>:assumed-role/aws-infra-ops-mcp-lab-runtime/<session-name>

It rejects:

  • Administrator roles

  • Unexpected assumed roles

  • IAM users

  • The AWS account root identity

  • Incorrect AWS accounts

  • Missing or malformed identity configuration

  • Incomplete STS responses

Only successful identity validation is cached for the lifetime of the MCP process.

Approved targets

The current server supports only:

Instance: web01
Service:  nginx

The instance must have these tags:

Tag

Value

Name

web01

MCPAccess

allowed

The model cannot provide arbitrary instance IDs, AWS queries, commands, files, services, document names, log groups, or metric names.

No remediation

The server does not provide tools to:

  • Start, stop, reboot, or terminate EC2 instances

  • Restart services

  • Change security groups or routes

  • Modify IAM

  • Execute arbitrary shell commands

  • Create or delete AWS resources

  • Change application configuration

  • Run Terraform

  • Open interactive SSM sessions

Any recovery action remains a separate, human-controlled activity.

Repository structure

aws-infra-ops-mcp/
├── aws_infra_ops_mcp/
│   ├── tools/
│   │   ├── instance_health.py
│   │   ├── instance_metrics.py
│   │   ├── recent_changes.py
│   │   ├── recent_errors.py
│   │   ├── service_journal.py
│   │   └── service_status.py
│   ├── __init__.py
│   ├── app.py
│   ├── aws.py
│   ├── policy.py
│   └── runtime_identity.py
├── infrastructure/
│   ├── modules/
│   ├── main.tf
│   ├── outputs.tf
│   ├── providers.tf
│   ├── terraform.tfvars.example
│   ├── variables.tf
│   └── versions.tf
├── .gitignore
├── pyproject.toml
├── README.md
└── server.py

Prerequisites

  • Python 3.11 or newer

  • Terraform 1.6 or newer

  • AWS CLI

  • AWS Session Manager plugin

  • Codex with local MCP support

  • An AWS source identity that can deploy the Terraform configuration

  • An AWS Region configured

The example infrastructure defaults to:

ap-southeast-1

Local installation

On Linux, macOS, or WSL:

cd <PROJECT_DIR>
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .

On Windows PowerShell:

Set-Location <PROJECT_DIR>
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e .

AWS profiles

Use separate profiles for deployment and diagnostics.

Deployment profile

The source or administrator profile is used by Terraform:

default

MCP runtime profile

The MCP server uses:

mcp-lab-runtime

Example AWS configuration:

[profile mcp-lab-runtime]
role_arn = arn:aws:iam::<AWS_ACCOUNT_ID>:role/aws-infra-ops-mcp-lab-runtime
source_profile = default
role_session_name = aws-infra-ops-mcp
duration_seconds = 3600
region = ap-southeast-1

Do not run Terraform using mcp-lab-runtime. Its restricted permissions are intentional.

Terraform deployment

Copy the example variables file:

cp infrastructure/terraform.tfvars.example infrastructure/terraform.tfvars

Update the values for your AWS account and environment.

Deploy using the source or administrator profile:

export AWS_PROFILE=default

terraform -chdir=infrastructure init
terraform -chdir=infrastructure fmt -check -recursive
terraform -chdir=infrastructure validate
terraform -chdir=infrastructure plan -out=tfplan
terraform -chdir=infrastructure apply tfplan

Terraform creates the lab infrastructure, including:

  • Networking

  • EC2 instance

  • EC2 instance profile

  • Systems Manager connectivity

  • CloudWatch log groups

  • CloudWatch Agent configuration

  • Custom SSM diagnostic documents

  • Restricted MCP runtime role

  • Read-only diagnostic IAM policy

Terraform uses local state in this example. State files and variable files are excluded from Git and must be stored securely.

Running the MCP server

Set the runtime profile and identity guard values:

export AWS_PROFILE=mcp-lab-runtime
export AWS_REGION=ap-southeast-1
export AWS_DEFAULT_REGION=ap-southeast-1
export AWS_SDK_LOAD_CONFIG=1
export MCP_EXPECTED_AWS_ACCOUNT_ID=<AWS_ACCOUNT_ID>
export MCP_EXPECTED_AWS_ROLE_NAME=aws-infra-ops-mcp-lab-runtime

Start the server:

aws-infra-ops-mcp

For a local stdio server, it may appear to wait without displaying a prompt. That is expected because it is waiting for MCP messages on standard input.

Connecting Codex

Add the server to your Codex configuration:

[mcp_servers.aws-infra-ops-lab]
command = "/absolute/path/to/aws-infra-ops-mcp/.venv/bin/python"
args = ["/absolute/path/to/aws-infra-ops-mcp/server.py"]
cwd = "/absolute/path/to/aws-infra-ops-mcp"

[mcp_servers.aws-infra-ops-lab.env]
AWS_PROFILE = "mcp-lab-runtime"
AWS_REGION = "ap-southeast-1"
AWS_DEFAULT_REGION = "ap-southeast-1"
AWS_SDK_LOAD_CONFIG = "1"
MCP_EXPECTED_AWS_ACCOUNT_ID = "<AWS_ACCOUNT_ID>"
MCP_EXPECTED_AWS_ROLE_NAME = "aws-infra-ops-mcp-lab-runtime"

Restart Codex after changing its MCP configuration.

Use /mcp to confirm the server and its six tools are available.

Example requests

Check the health of web01 and show the evidence source.
Show the EC2 metrics for web01 over the last 60 minutes.
Find recent errors for web01 during the last 15 minutes.
Check the nginx service state on web01.
Read the nginx journal for web01 over the last 30 minutes.
Show recent AWS control-plane activity associated with web01 and identify
whether each event came from the administrator or MCP runtime role.

A broader investigation could ask:

Investigate why nginx on web01 appears unavailable. Correlate EC2 health,
CloudWatch metrics, recent errors, nginx service state, the nginx journal, and
recent AWS control-plane activity. Separate confirmed evidence from inference,
state the limitations, and do not perform remediation.

Troubleshooting

Terraform returns AccessDenied

Confirm Terraform is using the source or administrator profile:

export AWS_PROFILE=default

The MCP runtime role is intentionally unable to manage the Terraform infrastructure.

The MCP server rejects its AWS identity

Check:

  • AWS_PROFILE

  • AWS account ID

  • Runtime role ARN

  • MCP_EXPECTED_AWS_ACCOUNT_ID

  • MCP_EXPECTED_AWS_ROLE_NAME

  • The source profile’s current authentication session

Confirm the runtime identity:

aws sts get-caller-identity --profile mcp-lab-runtime

The ARN should include:

assumed-role/aws-infra-ops-mcp-lab-runtime/

CloudWatch Logs returns AccessDenied

Confirm the current Terraform-managed runtime policy has been deployed.

The approved CloudWatch log-group resource ARNs must include the suffix required for querying their streams.

Service status or journal requests fail

Confirm:

  • web01 is online in Systems Manager

  • SSM Agent is running

  • The custom SSM documents exist

  • The runtime policy references the approved documents and instance

  • The request uses web01 and nginx

Recent errors are empty

Confirm:

  • CloudWatch Agent is running

  • The approved log groups contain current streams

  • The requested time range covers the expected event

  • The event matches the server’s fixed error query

Recent CloudTrail changes are empty

CloudTrail Event History is eventually consistent. Wait several minutes and retry with an appropriate lookback.

An empty result does not prove that no activity occurred.

Codex does not show the tools

Confirm:

  • The MCP configuration uses absolute paths

  • The virtual environment contains the package

  • The server starts successfully

  • Codex was restarted after the configuration changed

Current limitations

  • Only web01 is supported.

  • Only the nginx service is supported.

  • Dynamic fleet discovery is not implemented.

  • There is no HTTP or end-to-end application reachability tool.

  • CloudWatch log groups are fixed to the lab instance.

  • The journal tool cannot inspect arbitrary services or files.

  • CloudTrail results cover a fixed event allowlist.

  • Terraform state is local.

  • The example lab uses a public subnet for outbound connectivity.

  • Diagnostics are read-only.

  • Recovery remains operator-controlled.

Teardown and cost control

Teardown is destructive.

Use the Terraform source or administrator profile—not the MCP runtime role:

export AWS_PROFILE=default
terraform -chdir=infrastructure plan -destroy -out=destroy.tfplan

Review the saved plan carefully.

Apply only the reviewed destroy plan:

terraform -chdir=infrastructure apply destroy.tfplan

Verify that Terraform no longer tracks any resources:

terraform -chdir=infrastructure state list

Destroying the AWS resources stops their ongoing infrastructure costs. It does not remove the local source code, Git history, virtual environment, or Terraform files.

Future enhancements

Potential future improvements include:

  • Tag-based dynamic discovery of approved instances

  • Bounded fleet-health tools

  • Read-only HTTP or load-balancer health checks

  • Cross-account diagnostics using controlled role assumption

  • Remote MCP hosting

  • Multi-user authentication and authorization

  • Encrypted remote Terraform state with locking

  • Central application audit logging

  • Human-approved remediation workflows in a separately controlled service

Disclaimer

This project is a learning and demonstration environment. Review its IAM policies, networking, logging, data handling, and operational controls before adapting it for production use.

Available Tools

5 tools
get_instance_healthC

Check EC2 state and AWS system and instance health checks.

ParametersJSON Schema
NameRequiredDescriptionDefault
instance_nameYes

TDQS

C2.6/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full burden. It implies a read-only operation via 'Check' but does not disclose return format, potential errors, or the exact scope of health checks. This lacks the detail needed for an agent to understand side effects or limitations.

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

Conciseness3/5

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

The description is a single concise sentence, which is efficient, but it is under-specified. It provides a clear action but lacks any structural breakdown or additional context, making it borderline between appropriate and minimal.

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

Completeness2/5

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

For a simple one-parameter read-only tool without an output schema or annotations, the description is thin. It does not clarify what health checks are included, what the response contains, or how this relates to the sibling tools, leaving the agent with significant gaps.

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

Parameters2/5

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

The schema has one parameter, instance_name, with 0% description coverage. The description does not mention the parameter or how to specify the instance, relying solely on the parameter name which is somewhat self-explanatory but not explicitly documented.

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 clearly identifies the tool as checking EC2 state and AWS system/instance health checks, which is a specific verb+resource combination. It distinguishes from sibling tools like get_instance_metrics and get_service_status, though it could be more explicit about the exact health check details.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives. There is no mention of exclusions, prerequisites, or comparison with sibling tools such as get_instance_metrics or get_service_status.

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

get_instance_metricsC

Get fixed EC2 performance and status metrics from CloudWatch.

ParametersJSON Schema
NameRequiredDescriptionDefault
minutesNo
instance_nameYes

TDQS

C2.8/5.0
Behavior2/5

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

There are no annotations, so the description must carry the full burden of behavioral disclosure. It only states the metric source (CloudWatch) but does not reveal whether this is a read-only operation, how metrics are aggregated, whether results are time-bounded, or any rate limits. The word 'fixed' is ambiguous and not explained.

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

Conciseness4/5

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

The description is a single sentence with no wasted words, front-loading the action and resource. However, the term 'fixed' could be clearer, slightly reducing the overall conciseness benefit due to ambiguity.

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

Completeness2/5

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

Given there is no output schema or annotations, the description should provide more context about what metrics are returned, how the 'minutes' parameter influences results, and any limitations. The current one-liner is insufficient for an agent to invoke this tool reliably without further guesswork.

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

Parameters1/5

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

The input schema has two parameters (instance_name, minutes) with no descriptions, and the tool description does not mention them at all. With schema description coverage at 0%, the agent is left with no clue about what these parameters mean or how they affect the call, making this a severe 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?

The description clearly states the action (Get) and the resource (EC2 performance and status metrics) with a specific source (CloudWatch). It distinguishes itself from sibling tools that focus on health, errors, service status, or journal, making its purpose unambiguous.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus the sibling tools (e.g., get_instance_health, get_recent_errors). The description does not mention exclusions, alternatives, or conditions that would help an agent choose correctly.

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

get_recent_errorsC

Get recent CloudWatch application and operating-system errors.

ParametersJSON Schema
NameRequiredDescriptionDefault
minutesNo
instance_nameYes
maximum_resultsNo

TDQS

C2.9/5.0
Behavior2/5

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

With no annotations, the description must fully disclose behavior, but it only says 'recent' without defining the time window or clarifying that this is a read-only operation. It does not mention return format, pagination, or how the parameters affect results. The term 'recent' is vague and the description lacks critical behavioral details.

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?

The description is a single, clear sentence that is front-loaded with the core action. Every word is informative, with no filler or redundancy. It is appropriately concise for the simple function it describes.

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

Completeness2/5

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

Given the moderate complexity (3 parameters, no output schema, no annotations), the description is far too sparse. It does not explain what constitutes an error, how the parameters interact, or what the response will look like. The agent is left with insufficient context to use the tool reliably.

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

Parameters1/5

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

The description does not explain any of the three parameters (instance_name, minutes, maximum_results). Schema description coverage is 0%, so the description provides no additional meaning beyond the raw schema. The agent cannot infer parameter semantics from the description alone; it must guess or have prior knowledge.

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?

The description uses a specific verb ('Get') and clearly identifies the resource ('recent CloudWatch application and operating-system errors'). It distinguishes from sibling tools like get_instance_health or get_service_status, which focus on different data (health, status). There is no ambiguity about what this tool retrieves.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus the siblings. It does not mention scenarios, exclusions, or alternative tools. The agent is left to infer from the name alone that it is for errors, with no direction on how it differs from get_service_journal or get_instance_metrics.

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

get_service_journalA

Get a bounded nginx systemd journal through a fixed SSM document.

ParametersJSON Schema
NameRequiredDescriptionDefault
minutesNo
service_nameYes
instance_nameYes
maximum_resultsNo

TDQS

A3.5/5.0
Behavior3/5

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

With no annotations provided, the description carries the full burden. It adds 'bounded' and 'fixed SSM document' as behavioral context, but does not explain output format, pagination, or prerequisites like SSM agent availability. As a read operation, it is not misleading.

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?

The description is a single focused sentence, front-loaded with the main verb and resource. Every word adds meaning, with no unnecessary repetition or filler.

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

Completeness2/5

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

There is no output schema, and the description fails to specify the return format, bounding behavior, or potential prerequisites (e.g., SSM document requirements). It also does not differentiate from sibling tools, leaving the agent with limited operational context.

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

Parameters2/5

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

Schema description coverage is 0%, so the description must compensate. It does not directly explain any of the four parameters; 'bounded' loosely hints at minutes and maximum_results but does not clarify their meaning or the required parameters. This is a significant 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?

The description clearly states the action ('Get') and the resource ('bounded nginx systemd journal'), which is specific and distinct from sibling tools that focus on health, metrics, errors, or status. The term 'bounded' also adds scope.

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 context implies usage is for retrieving nginx journal logs, but it does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions. It relies on the tool's name and sibling set for differentiation.

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

get_service_statusB

Check the current state of an approved service on an instance.

ParametersJSON Schema
NameRequiredDescriptionDefault
service_nameYes
instance_nameYes

TDQS

B3/5.0
Behavior3/5

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

With no annotations, the description carries the full burden. It adds useful context ('approved service', 'current state') but omits behavioral details such as read-only nature, return format, permissions, or error behavior. It's minimally adequate but not rich.

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

Conciseness4/5

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

The description is a single, front-loaded sentence with no extraneous words. It efficiently states the tool's action and target, earning its place despite its brevity.

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

Completeness3/5

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

For a simple two-parameter tool with no output schema, the description is reasonably complete but leaves gaps: it doesn't explain what 'state' means, what a return value looks like, or what 'approved service' implies. Given sibling tools and no annotations, more context would improve completeness.

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

Parameters2/5

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

Schema description coverage is 0%, and the description adds no meaning to the parameters. While parameter names (instance_name, service_name) are somewhat self-explanatory, the description does not elaborate on format, allowed values, or how they relate to the 'approved service' concept, leaving the agent to infer entirely from names.

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 uses a specific verb ('check') and resource ('state of an approved service on an instance'), clearly identifying the tool's purpose. It distinguishes from siblings like get_instance_health (instance-level) and get_recent_errors (errors), though it doesn't explicitly name alternatives.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus alternatives. The description implies usage for checking service status but offers no context, exclusions, or comparisons to sibling tools like get_service_journal or get_instance_metrics.

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. 5 tool updatesv0.1.0
    • First observedget_instance_health
    • First observedget_instance_metrics
    • First observedget_recent_errors
    • First observedget_service_journal
    • First observedget_service_status
Deploy Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.4/5.0

Scored across 5 tools

Disambiguation5/5

Each tool clearly targets a distinct aspect: instance health, metrics, errors, service status, and service journal. There is minimal overlap, and the descriptions specify distinct data sources (CloudWatch, SSM) and resources (EC2 instance vs. service).

Naming Consistency5/5

All tool names follow a uniform `get_` prefix followed by a descriptive noun phrase, such as `get_instance_health` and `get_service_journal`. The pattern is consistent and predictable, making the API easy to navigate.

Tool Count5/5

With 5 tools, the server is well-scoped for a monitoring-focused infrastructure ops API. Each tool serves a specific operational need, and the count is neither too thin nor bloated for the apparent purpose.

Completeness4/5

The tool set covers core monitoring needs: health, metrics, errors, service status, and logs. Minor gaps exist (e.g., no list operations, no instance control), but for a read-only diagnostics server, the coverage is solid and workable.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • aws-readonly-mcp

    ziyuyu23
    A
    license
    Not graded
    quality
    C
    maintenance
    A read-only MCP server that lets an LLM inspect an AWS account — list EC2 instances, S3 buckets, IAM users, and cost — with a structural guarantee against any mutations.
    MIT

  • vps-ops-mcp

    Akdag94
    A
    license
    A
    quality
    A
    maintenance
    A safe, structured MCP server that lets AI inspect and operate a VPS through typed, allowlisted tools for nginx, PM2, SSL, UFW, fail2ban, with read-only defaults and opt-in mutations.
    6
    6
    2
    MIT