Skip to main content
Glama
deenesjakoruzh
herrerogusano

AWS Resource MCP

by herrerogusano
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

AWS Resource MCP

Local MCP server, developed in Python, for querying real resources from an AWS account in read-only mode.

Status

Phase 9 is implemented. The server combines uniform inventory, conservative activity analysis, explicit diagnostics, economic analysis, and least-privilege IAM policies generated from the actual operations log.

Related MCP server: aws-mcp-server

Planned scope

  • Local MCP transport via stdio.

  • Primary region: eu-west-1.

  • AWS queries exclusively read-only and least-privilege.

  • Available tools: health_check(), listar_recursos_aws(), analizar_actividad_recursos(), diagnosticar_cobertura_aws(), analizar_riesgo_costes(), revisar_free_tier(), and consultar_costes_aws().

  • Cost Explorer is blocked until ephemeral consent is received for an exact request.

  • No deployment on AWS or CD.

Reliability

Phase 10 incorporates local integration, contract, security, performance, and MCP protocol tests. The inventory also applies AWS_MCP_MAX_REQUESTS_PER_TOOL (250 by default) before each SDK call; when exhausted, it preserves the result and returns partial_request_budget_exhausted.

Continuous integration runs formatting, linting, compilation, deterministic IAM validation, and local tests on every pull request. It does not configure AWS credentials or run AWS operations.

Using with Codex

Codex is the primary client. Use the package entry point uv run aws-resource-mcp over stdio, configure any AWS profile outside the repository, and begin with natural-language questions such as "What resources do I have in eu-west-1?". When a response is partial_pending_consent, Codex must explain the exact operation and wait for explicit approval; it never creates persistent consent. See Codex integration and the demo.

Release v0.1.0

The first version is ready for review: it includes the read-only guard, ephemeral consent, Codex integration, and CI. See the release checklist to verify it locally and run the safe demo.

Development

The project is managed with uv and Python 3.12 or later.

Install dependencies

uv sync

Run the server

uv run aws-resource-mcp

For diagnostics it can also be run as a module:

uv run python -m aws_resource_mcp.server

The server uses stdio: it expects an MCP client to exchange messages over standard input and output. It can be opened with MCP Inspector using the tools included in the SDK:

uv run mcp dev src/aws_resource_mcp/server.py

Run the tests

uv run pytest

Generate and validate IAM policies

uv run aws-resource-mcp-generate-iam
uv run aws-resource-mcp-generate-iam --check

Generation is local, deterministic, and uses no credentials. The project does not create or modify roles or policies in AWS. The policies separate free operations, reads that require consent, and the combined maximum; IAM permission never replaces application consent.

Run the AWS inventory

Before the real diagnostic, check which identity the local configuration will resolve:

aws sts get-caller-identity

Then run the inventory in the default region eu-west-1:

uv run python -m aws_resource_mcp.aws.inventory

The region and shared profile are optional:

uv run python -m aws_resource_mcp.aws.inventory --region eu-central-1 --profile example

No keys are stored in the project. Boto3 uses its standard credential resolution chain; if AWS_PROFILE or --profile is specified, it only selects a profile that must already exist outside the repository.

MCP Tools

health_check

health_check(check_aws=True) separates local health from AWS accessibility. Without arguments it makes at most one protected STS call; with check_aws=false it uses no network. It returns version, transport, tools, and registered adapters, region, cost policy, and zero billable operations. Its states are:

  • ok: server and configuration valid; STS responded when requested.

  • degraded: the server works, but credentials are missing or STS is not accessible.

  • error: the secure configuration or internal registries cannot be initialized.

Identity is anonymized: only the general principal type and, when present, a masked account are kept. It does not run inventory, Resource Explorer, adapters, CloudTrail, or CloudWatch.

listar_recursos_aws

Queries the AWS inventory available to the local credentials without modifying resources. Parameters:

  • region: limits the search to one region; without a value it uses all available coverage.

  • services: filters by services such as lambda, s3, ec2, or rds.

  • include_account_id: allows omitting the account ID from the response to make it easier to anonymize.

  • resource_types: filters by dynamic types such as ec2:instance.

  • query: searches by text or name.

  • all_regions: uses enabled regions when region is not specified.

  • include_details: includes service-specific metadata inside details.

  • include_cost_indicators: includes potential cost signals without asserting actual spend.

  • confirm_potentially_billable_operations: legacy parameter that no longer grants permissions.

  • include_activity_summary: adds a brief summary using only fields already obtained; it does not query CloudTrail or CloudWatch.

  • consent_request_id, consent_action, and approved_services: resume or cancel an ephemeral, scoped request.

  • timeout_seconds: configurable budget between 1 and 120 seconds.

Example of arguments sent by an MCP client:

{
  "region": "eu-west-1",
  "services": ["lambda", "s3"],
  "include_account_id": false,
  "all_regions": true
}

The first call returns the resources obtained through allowed operations. If completing S3, SQS, or SNS requires billable operations, it returns partial_pending_consent, pending_operations, and a request that expires in five minutes. It does not run those operations until an explicit second call:

{
  "consent_request_id": "<id devuelto por la primera llamada>",
  "consent_action": "approve",
  "approved_services": ["s3"]
}

Approval is single-use, tied to the original identity and scope, and limits operations, regions, and requests. Discovery and enrichment are authorized separately; an additional page requires a new request. consent_action: "cancel" does not run the AWS inventory.

The states distinguish complete_for_requested_scope, partial_pending_consent, partial_timeout, partial_permission_denied, partial_unavailable, consent_cancelled, and error. An empty list only means the service was empty when queried.

resources, all_resources, and resources_by_service represent the same deduplicated inventory. Each resource contains id, arn, name, service, resource_type, region, account_id, state, created_at, sources, details, cost_indicators, and activity. The tool does not calculate costs, does not query Free Tier, and does not perform write operations.

analizar_actividad_recursos

Analyzes the last known signal using the same log and model for all resources. It accepts filters by services, regions, and resource_ids, plus inactive_days, lookback_days, include_administrative_events, and configurable limits. The CloudTrail history is limited to 90 days and is queried per region, not once per resource.

The response separates last_functional_usage_at, last_administrative_activity_at, last_configuration_change_at, and last_state_change_at. best_known_activity_at always also indicates the signal type. An active state, a Describe* call, or a modification date is not presented as functional usage.

Per-resource states are active, inactive_candidate, unknown, not_supported, or error. An inactive candidate is only an item for review: it requires sufficient age, a relevant source queried, and no recent contradictory evidence. Missing permissions, insufficient sources, or ambiguous relationships produce unknown, not a false certainty of inactivity.

CloudWatch could provide functional metrics, but GetMetricData, GetMetricStatistics, and ListMetrics are registered as potentially billable and blocked. include_paid_sources=true only requests the structured explanation; it does not constitute consent and never runs those operations in this phase.

diagnosticar_cobertura_aws

Explains what the MCP can actually query without enumerating resources. It accepts services and regions filters and allows omitting the permissions, activity, or cost policy sections.

It checks STS, enabled regions, existing Resource Explorer indexes, adapter registration and capabilities, free activity sources, and blocked operations. Checks are limited to five regions per run, one CloudTrail sample, and no CloudWatch calls.

Coverage states distinguish available, partial, unavailable, not_configured, permission_denied, blocked_by_cost_policy, not_supported, not_checked, and error. An operation declared as allowed by the policy is not presented as proven IAM permission: the diagnostic does not run service inventories to test it.

Example:

{
  "services": ["ec2", "rds"],
  "regions": ["eu-west-1"],
  "include_activity_sources": true
}

Limitations indicate impact, whether the MCP can continue, whether permissions are missing, whether resolving them would require writes, and whether cost could exist. The diagnostic never performs the suggested action.

analizar_riesgo_costes

Prioritizes resources using inventory indicators and, optionally, the common activity pipeline. It returns none_detected, low, medium, high, critical, or unknown, an explainable score, and non-executable recommendations. A signal does not confirm spend, and none_detected does not mean zero cost.

include_free_tier=true adds official Free Tier data. include_actual_cost=true only prepares a Cost Explorer consent: it does not perform the query.

revisar_free_tier

Queries GetFreeTierUsage and GetAccountPlanState, operations AWS documents as free. It separates monthly limits, forecast, plan, and credits. It may return partial or unknown information due to permissions, update lag, an exhausted offer, or eligibility differences. It does not claim that a specific resource is free.

consultar_costes_aws

Prepares an aggregated GetCostAndUsage query for an exact period and filters. The first call runs zero AWS operations and returns an ephemeral request with the published price of 0.01 USD per request on the primary view. A second call with consent_action="approve" runs at most one page; each additional page requires new consent. cancel does not call AWS.

Granularity can be MONTHLY or DAILY; end_date is exclusive. Forecast, per-resource detail, linked accounts, and custom billing views are not implemented in this phase.

AWS Inventory

Boto3 is the official AWS SDK for Python. The inventory layer uses:

  • STS GetCallerIdentity to identify the account and effective identity.

  • EC2 DescribeRegions to discover only enabled regions.

  • Resource Explorer to dynamically discover resources and supported types through existing indexes and views.

  • A common adapter registry for Lambda, S3, EC2/EBS/VPC, RDS/Aurora, DynamoDB, ECS/Fargate, API Gateway, CloudFormation, SQS, SNS, IAM, CloudFront, and Route 53.

  • CloudTrail LookupEvents for the free regional management event history of the last 90 days.

Lambda and S3 were the first implemented services, but they no longer keep special architectural paths. All adapters declare metadata, Boto3 operations, scope, types, details, and indicators through the same contract. Service-specific details live only inside details.

Results are deduplicated by ARN or, if missing, by type, region, and identifier/name. An aggregator index is preferred; with local indexes, results are combined and coverage is partial. If Resource Explorer is unavailable, all selected adapters that support discovery are run.

The absence of credentials or the inability to identify the account is a global error for inventory, but only a degraded state for local health. The diagnosis preserves its local checks and safely omits AWS-dependent ones.

All Boto3 calls first pass through a central log. Unregistered, write, or unknown-cost operations are blocked. The free-only mode remains active throughout the process. S3, SQS, and SNS can count requests: their enumerations are presented as pending, and only an exact ephemeral grant allows them to be executed. The guard counts unique operations and real requests separately.

Examples for an MCP client: "What resources are in my account?", "List EC2 instances in eu-west-1", "Search for resources named web" or "Show me deployed RDS types". Resource Explorer offers broad, not universal, coverage.

Documentation

Available Tools

7 tools
analizar_actividad_recursosA

Analyze last known AWS resource activity with conservative semantics.

Free service API fields and CloudTrail Event History management events are
combined through the common adapter pipeline. Functional usage,
administrative activity, configuration changes, and state signals remain
separate. Event History is regional, limited to 90 days, and does not
normally include data events such as S3 GetObject, so unknown results are
expected. CloudWatch could improve functional-usage coverage but is always
blocked in this phase: setting ``include_paid_sources`` only requests a
structured explanation and never grants consent or executes a metric call.
The operation is read-only, bounded, and may return partial results.
ParametersJSON Schema
NameRequiredDescriptionDefault
regionsNo
servicesNo
max_regionsNo
resource_idsNo
inactive_daysNo
lookback_daysNo
max_resourcesNo
timeout_secondsNo
include_paid_sourcesNo
max_events_per_resourceNo
include_administrative_eventsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.6/5.0
Behavior5/5

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

With no annotations provided, the description bears full responsibility for transparency. It does an excellent job: it details the data sources (free API, CloudTrail Event History), the regional and temporal scope (90-day limit), expected unknowns (data events excluded), the non-execution of paid sources, and the bounded, read-only nature. This sets correct expectations for the agent.

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 6 sentences long and front-loads the purpose. However, it includes technical jargon (e.g., 'common adapter pipeline') that could be simplified. While not excessively long, it is not as concise as it could be; some sentences could be merged or removed without losing essential information.

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?

Given the complexity (11 parameters, output schema exists), the description covers the core behavior, data sources, and limitations well. It mentions partial results and the non-execution of paid sources. Since an output schema exists, the description does not need to detail return values. However, it could briefly mention what the output contains (e.g., last activity timestamps per resource) to aid understanding, but this is not a major gap.

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 input schema has 11 parameters with 0% description coverage, meaning the schema provides no textual help. The description only explicitly mentions one parameter (include_paid_sources) and explains its behavior. The other 10 parameters (regions, services, max_regions, resource_ids, inactive_days, lookback_days, max_resources, timeout_seconds, max_events_per_resource, include_administrative_events) are not described. This leaves the agent without guidance on their semantics, which is inadequate.

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 states the tool's purpose: 'Analyze last known AWS resource activity with conservative semantics.' It identifies the resource (AWS resources) and action (analyze activity). However, it does not differentiate from sibling tools like listar_recursos_aws or diagnosticar_cobertura_aws, so it loses the highest score.

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 description implies when to use the tool (for analyzing resource activity with free data sources) and provides context about limitations (regional, 90-day, no data events). It explains that include_paid_sources does not grant consent, giving guidance on that parameter. However, it does not explicitly state when NOT to use this tool or suggest alternatives, so the guidance is implied rather than explicit.

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

analizar_riesgo_costesA

Prioritize potential AWS cost risk without treating it as actual spend.

The analysis uses the common inventory model and its cost indicators.
Optional activity is merged through the existing uniform activity tool.
Free Tier data uses the officially free API. ``include_actual_cost=True``
only prepares a separate Cost Explorer consent request; it does not grant
consent or execute a potentially billable operation. Recommendations are
informational and no AWS resource is changed.
ParametersJSON Schema
NameRequiredDescriptionDefault
regionsNo
servicesNo
period_daysNo
resource_idsNo
max_resourcesNo
include_activityNo
include_free_tierNo
include_actual_costNo

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?

With no annotations, the description fully explains critical behaviors: it does not change AWS resources, does not grant consent or execute billable operations, uses free API for free tier, and merges activity through existing tools. This provides sufficient transparency.

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 concise at 5 sentences, with the purpose front-loaded. Each sentence adds distinct value: purpose, model used, activity merging, free tier and include_actual_cost clarification, and non-destructive nature. No unnecessary repetition.

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?

With 8 parameters and 0% schema coverage, the description should compensate by explaining key parameters and output. Only include_actual_cost is addressed. The output schema exists but is not described. The complexity is medium-high, but the description provides insufficient detail for effective tool use.

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%, yet the description only explains the include_actual_cost parameter. The other 7 parameters (regions, services, period_days, etc.) receive no explanation, leaving the agent to infer from names and types. This is insufficient given the low coverage.

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 first sentence clearly states the tool's purpose: 'Prioritize potential AWS cost risk without treating it as actual spend.' It uses a specific verb (prioritize) and resource (cost risk), and distinguishes from sibling tools like consultar_costes_aws which deal with actual spend.

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

Usage Guidelines4/5

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

The description implicitly differentiates from siblings by emphasizing risk assessment rather than actual spend. It mentions when include_actual_cost=True is appropriate, but does not explicitly state when to use this tool versus alternatives.

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

consultar_costes_awsA

Prepare or execute one exact, potentially billable Cost Explorer query.

The first call performs no AWS operation. It returns an expiring,
single-use request that states the exact period, filters, operation,
maximum request count, and estimated API charge. Calling again with the
request id and ``consent_action="approve"`` executes at most one
GetCostAndUsage page. A continuation page always needs a new consent.
``cancel`` performs no AWS call. Approval never authorizes another
operation, period, filter, identity, forecast, or resource-level query.
ParametersJSON Schema
NameRequiredDescriptionDefault
regionsNo
end_dateNo
servicesNo
max_pagesNo
start_dateNo
granularityNoMONTHLY
resource_idsNo
consent_actionNo
group_by_serviceNo
include_forecastNo
consent_request_idNo
include_resource_levelNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.8/5.0
Behavior5/5

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

No annotations provided, so description carries full burden. It discloses that the first call is free, execution is billable, approval is single-use, continuation pages need new consent, and it never authorizes other operations. No contradictions.

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?

Description is efficient, explaining the two-step consent flow in three sentences. Could be more structured (e.g., bullet points) but remains clear and concise.

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?

Adequately explains the consent workflow, but leaves parameter details completely unaddressed. With 0% schema coverage and 12 parameters, more parameter context is needed for completeness. Output schema exists but does not help with parameter usage.

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 coverage is 0% and description does not explain any of the 12 parameters (e.g., 'regions', 'start_date', 'consent_action'). It only references abstract concepts like 'period' and 'filters'. Falls short of compensating for missing schema descriptions.

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 states the tool prepares or executes a single Cost Explorer query, distinguishing between a preview call and an execution call. However, it does not differentiate from sibling tools like 'diagnosticar_cobertura_aws' or 'listar_recursos_aws'.

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

Usage Guidelines4/5

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

Provides explicit workflow guidance: first call for preview, second call with 'consent_action=approve' to execute, and 'cancel' does nothing. Does not mention when to prefer this over alternatives or any prerequisites.

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

diagnosticar_cobertura_awsA

Explain which AWS coverage is reachable and why it may be partial.

This read-only diagnostic checks STS, enabled Regions, existing Resource Explorer indexes, the shared adapter registry, free activity sources, and the central cost policy. It does not inventory resources, create indexes, change IAM, enable Regions, or run CloudWatch. Adapter permissions are reported conservatively because service inventory calls are not executed. Results may be partial and never prove that an unqueried service is empty.

ParametersJSON Schema
NameRequiredDescriptionDefault
regionsNo
servicesNo
include_cost_policyNo
include_permissionsNo
include_activity_sourcesNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.3/5.0
Behavior5/5

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

With no annotations provided, the description fully carries the burden of behavioral disclosure. It explicitly states the tool is read-only, lists what it checks, and highlights limitations: adapter permissions reported conservatively, results may be partial, and never prove emptiness. This is comprehensive and transparent, leaving no hidden behaviors.

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 concise and well-structured: a one-sentence purpose follows by a bullet-like list of checks and non-actions, then caveats. Every sentence adds value without fluff. It is front-loaded with the primary purpose. Ideal for quick comprehension.

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?

Given the complexity (5 parameters, output schema exists), the description covers the diagnostic scope, limitations, and non-actions well. The output schema explains return values, so that gap is acceptable. However, it omits how parameters influence behavior, which is a notable hole for tool invocation. Overall, mostly complete but missing parameter-behavior links.

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 for parameter meanings. However, it does not describe any of the 5 parameters (regions, services, include_cost_policy, include_permissions, include_activity_sources). The general diagnostic scope indirectly relates, but no specific parameter guidance is given. This is a significant gap, resulting in a low score.

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 tool's purpose: 'Explain which AWS coverage is reachable and why it may be partial.' It uses specific verbs (explain, checks) and lists concrete resources and checks (STS, enabled Regions, Resource Explorer indexes). This distinguishes it from siblings like listar_recursos_aws (resource listing) or analizar_riesgo_costes (cost risk analysis), providing a unique and precise purpose.

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

Usage Guidelines4/5

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

The description provides clear context on when to use the tool by stating it is a read-only diagnostic and listing what it does not do (inventory resources, create indexes, change IAM, etc.). It also includes caveats about partial results. However, it does not explicitly compare to siblings or provide when-not-to-use guidance, so it misses the highest tier.

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

health_checkA

Check local server health and optionally perform one guarded STS call.

The AWS check never runs inventory, adapters, Resource Explorer, CloudTrail, CloudWatch, or any regional scan. Missing credentials degrade AWS access but do not mean the local MCP server is down.

ParametersJSON Schema
NameRequiredDescriptionDefault
check_awsNo

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?

Without any annotations, the description carries full burden. It explains that missing credentials degrade AWS access but do not indicate server down, and clarifies the limited scope of the AWS check. The term 'guarded STS call' is somewhat vague but still informative.

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 short paragraphs with no wasted words. The purpose is stated in the first sentence, and additional constraints form a second paragraph. Every sentence adds value.

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?

For a simple tool with one parameter and an existing output schema, the description covers the main point. It could explain what 'local server health' entails or what the output looks like, but the output schema likely provides that.

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 schema shows one optional boolean 'check_aws' with 0% description coverage. The description mentions 'optionally perform one guarded STS call' but does not explicitly link this to the parameter. It adds some meaning but could be more direct.

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 starts with 'Check local server health and optionally perform one guarded STS call', which provides a specific verb and resource. It clearly distinguishes from sibling tools like 'diagnosticar_cobertura_aws' by focusing on health rather than AWS-specific diagnostics.

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 description lists what the AWS check does NOT do (e.g., no inventory, adapters, regional scans), giving implicit context for when not to use it. However, it does not explicitly name alternative tools for those cases, leaving the agent to infer usage boundaries.

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

listar_recursos_awsA

Discover AWS resources through locally available credentials, read-only.

Runs free read-only discovery first. Operations that AWS can meter as
requests are returned as pending and are not executed. To continue, call
this same tool with the short-lived ``consent_request_id``,
``consent_action="approve"``, and an explicit subset in
``approved_services``. Approval is single-use, identity- and scope-bound,
request-limited, and does not authorize enrichment or extra pagination.
``consent_action="cancel"`` performs no AWS inventory call. The legacy
``confirm_potentially_billable_operations`` flag is retained for signature
compatibility but grants no permission.

Every service uses the same adapter pipeline and normalized resource model.
Coverage can be partial because of pending consent, timeout, permissions,
unavailable APIs, or Resource Explorer configuration. An empty result is
therefore distinct from a service that was not queried. This tool never
writes resources, lists S3 objects, reads queue messages, publishes topics,
calculates actual costs, or guarantees that a metered request is free.
ParametersJSON Schema
NameRequiredDescriptionDefault
queryNo
regionNo
servicesNo
all_regionsNo
consent_actionNo
resource_typesNo
include_detailsNo
timeout_secondsNo
approved_servicesNo
consent_request_idNo
include_account_idNo
include_cost_indicatorsNo
include_activity_summaryNo
confirm_potentially_billable_operationsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.3/5.0
Behavior5/5

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

With no annotations provided, the description fully discloses behavioral traits: read-only nature, consent action details, conditions for partial coverage, and explicit list of operations it never performs. This level of detail is exceptional for transparency.

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 front-loaded with the main purpose and structured into logical paragraphs. While every sentence contributes information, it is somewhat verbose and could be more concise. Overall, it is clear and well-organized.

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?

Given the tool's complexity (14 parameters, consent workflow, output schema), the description covers essential aspects: how to initiate discovery, how to handle pending operations, and what limitations exist. It does not detail the output schema (provided separately) but sets realistic expectations about coverage and behavior.

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?

Schema description coverage is 0%, so the description must compensate. It adds value for consent-related parameters (consent_action, approved_services, consent_request_id) by explaining their role in the workflow. However, many parameters (e.g., include_cost_indicators, include_activity_summary) are not described, leaving the agent to rely on property names alone.

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 tool's purpose: 'Discover AWS resources through locally available credentials, read-only.' It uses specific verbs and resource, and further distinguishes by detailing what it does not do (e.g., never writes resources, lists S3 objects). This provides clear differentiation from potential sibling tools.

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

Usage Guidelines4/5

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

The description explains the two-step consent workflow for billable operations, guiding when to call the tool again. While it doesn't explicitly compare to sibling tools, the context it provides (read-only discovery, consent mechanism) helps the agent determine appropriate usage scenarios.

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

revisar_free_tierA

Review account-plan and Free Tier usage without querying billed costs.

AWS officially documents programmatic Free Tier usage and account-plan monitoring at no cost. This read-only tool uses only GetFreeTierUsage and GetAccountPlanState. It does not call Cost Explorer, prove that a resource is free, or guarantee future eligibility. Usage can be estimated, delayed, absent after a limit is exhausted, or unavailable because of IAM.

ParametersJSON Schema
NameRequiredDescriptionDefault
servicesNo
max_pagesNo
include_forecastNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.9/5.0
Behavior4/5

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

With no annotations, the description carries full burden. It discloses limitations: does not call Cost Explorer, usage can be estimated/delayed/absent, and IAM restrictions. This provides good behavioral context.

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 focused with a clear opening sentence and brief additional details. It could be slightly more concise but is not verbose.

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?

The description covers purpose and limitations but omits parameter details. An output schema exists, so return values are not needed, but the lack of parameter explanation is a gap.

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%, yet the description does not explain any of the three parameters (services, max_pages, include_forecast). The agent only has parameter names and types, lacking meaning beyond that.

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 tool reviews account-plan and Free Tier usage without querying billed costs, using specific AWS APIs. It distinguishes itself from sibling tools like consultar_costes_aws by explicitly avoiding Cost Explorer.

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

Usage Guidelines4/5

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

The description implies when to use (free tier monitoring, not billed costs) and what it does not do (prove free, guarantee eligibility). It lacks explicit alternatives but context with sibling tools makes it clear.

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. 7 tool updatesv0.1.0
    • First observedanalizar_actividad_recursos
    • First observedanalizar_riesgo_costes
    • First observedconsultar_costes_aws
    • First observeddiagnosticar_cobertura_aws
    • First observedhealth_check
    • First observedlistar_recursos_aws
    • First observedrevisar_free_tier
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/5.0

Scored across 7 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: health check, coverage diagnosis, resource listing, activity analysis, cost risk, free tier, and cost queries. No two tools overlap in functionality.

Naming Consistency4/5

All names use snake_case and are descriptive, but there is an inconsistency in language: one tool is in English (health_check) while the rest are in Spanish. This is a minor deviation from a consistent pattern.

Tool Count5/5

Seven tools is a well-scoped set for a server focused on AWS resource discovery and cost analysis. Each tool covers a distinct aspect without being too few or too many.

Completeness4/5

The tool surface covers the main areas of health, coverage, resource discovery, activity, and cost (including free tier and actual cost). Minor gaps like direct resource detail queries are addressed by the generic listing tool, so overall completeness is high.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Lambda MCP Server

    aayushmittall
    F
    license
    Not graded
    quality
    D
    maintenance
    A stateless Python MCP server packaged as a custom AWS Lambda container image, exposing basic tools like hello, add, and current_time through an API Gateway HTTP API.
    -

  • mcp-aws

    Preeti325
    A
    license
    Not graded
    quality
    C
    maintenance
    This MCP server provides tools for inspecting AWS cloud infrastructure, including listing S3 buckets, EC2 instances, and fetching CloudWatch logs using your local AWS credentials.
    2 npm
    MIT