CloudOps MCP 是一个只读的模型上下文协议服务器，通过一组小型、类型化、有边界的工具，向 AI 智能体暴露标准化的运维基础设施上下文（日志、指标、部署、健康状态）。
调查事件的智能体需要运维上下文：最近发生了什么变化、错误率如何、日志说了什么。它不需要对云 API 的无限制访问，也不应该由它来决定什么是根本原因。
CloudOps MCP 位于两者之间：
Cloud APIs / observability systems
|
Provider adapters
|
Normalized operational domain
|
Deterministic services
|
MCP tools
|
AI agent每一层进一步标准化并缩小智能体可以请求的范围。提供商适配器将供应商 API 转换为共享领域模型。服务以确定性方式应用边界、排序和聚合，对每个提供商都相同。MCP 工具将其暴露为一个小型、类型化的表面。
CloudOps MCP 返回运维事实，而非根本原因结论。一个工具可以说“错误率从 0.4% 增加到 8% 在 14:06”；它不会说“部署导致了中断”。该判断属于智能体，使用 CloudOps MCP 作为证据提供的事实。
Related MCP server: cloud-chat-assistant
六个工具，全部只读且有边界：
工具 | 目的 |
| 列出已知服务以及每个服务配置了哪些能力。 |
| 提供商报告的服务健康状态。绝不从日志或指标推断。 |
| 最近的部署事件，受时间范围和数量限制。 |
| 日志事件，受时间范围、数量和消息长度限制。 |
| 带有确定性聚合（最小值/最大值/平均值/最新值）的指标序列；原始数据点是可选的且有边界。 |
| 复合视图：最近的部署、配置的快照指标、最近的日志和健康状态，在一次有边界的调用中。 |
get_operational_snapshot 组合了其他五个工具使用的相同原始服务，并发运行所有四个独立查询。它从不直接与提供商通信，也绝不会因为某个部分不可用而整体失败，每个部分报告自己的状态。
构造上只读。 提供商接口不暴露任何修改方法。没有通往写入 API 的代码路径。
提供商无关的服务标识。 服务由 (service, environment) 标识。供应商特定的标识符（CloudWatch 日志组、Kubernetes 对象名称）保留在提供商绑定的内部，绝不成为公共契约的一部分。
规范、可扩展的指标。 error_rate、latency_p99 等名称是我们的，不是供应商的。从规范名称到真实指标的映射存在于每个服务的配置中。词汇表是开放的，不是固定的枚举。
有边界的查询。 每个遥测查询都有时间范围上限和数量上限。调用者可以请求更少；但不能请求无边界的数据。
显式的数据可用性。 每个集合报告 SUCCESS、EMPTY、PARTIAL 或 FAILED 之一。缺失的数据永远不会被静默视为“健康”或“什么都没发生”。
可用性与结果分离。 NOT_CONFIGURED（未连接提供商）和 EMPTY（成功查询，零匹配）是不同的状态，绝不混为一谈。
来源而不泄露内部细节。 当提供商适配器提供时，单个结果携带 provider 和 source。用于调用提供商的内部引用绝不会复制到公共输出中。
处处使用 UTC。 所有时间戳都感知时区并标准化为 UTC；朴素日期时间在模型边界被拒绝。
MCP 服务器内部没有 LLM。 没有摘要、没有分类、没有对日志内容的推理。日志消息被视为不透明的、不可信的文本。
没有因果推理。 工具报告什么发生了变化以及何时发生。解释原因留给智能体。
模拟模式是默认模式，也是尝试 CloudOps MCP 的主要方式。它不需要云账户。
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"运行服务器（stdio 传输）：
python -m cloudops_mcp.server或者，如果包已安装其控制台脚本：
cloudops-mcp服务器通过 stdio 使用 MCP 协议，并期望客户端在另一端。要直接从 Python 使用官方 SDK 的客户端尝试：
import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
async def main():
params = StdioServerParameters(command="python", args=["-m", "cloudops_mcp.server"])
async with stdio_client(params) as (read, write):
async with ClientSession(read, write) as session:
await session.initialize()
tools = await session.list_tools()
print([t.name for t in tools.tools])
result = await session.call_tool(
"get_operational_snapshot",
{"service": "checkout-api", "environment": "production"},
)
print(result.structured_content)
asyncio.run(main())使用 CLOUDOPS_MCP_SCENARIO 选择场景（默认为 healthy）：
场景 | 模拟内容 |
| 一个配置了所有能力的服务，没有任何异常。 |
| 一次部署，然后是错误率和延迟变化，然后是超时日志。 |
| 一个能力在查询中失败，一个未配置，其余成功。 |
CLOUDOPS_MCP_SCENARIO=bad_deploy python -m cloudops_mcp.serverbad_deploy 在固定时间戳植入三个相关事实：一次部署，几分钟后的指标变化，以及之后不久的超时日志行。CloudOps MCP 仅报告这三个事实，不再多言。它不声称部署导致了错误，该推理完全留给消费智能体。
pip install -e ".[aws]" # runtime only
pip install -e ".[dev,aws]" # developmentCLOUDOPS_MCP_MODE=aws CLOUDOPS_MCP_CONFIG=/path/to/cloudops.toml cloudops-mcp参见 examples/aws-cloudwatch.toml 获取完整示例配置。它仅使用占位符值，该文件中不应包含真实的账户 ID、ARN 或凭证。
凭证完全来自 boto3 的标准提供商链：AWS_PROFILE、AWS_REGION / AWS_DEFAULT_REGION、环境凭证或 IAM 角色。CloudOps MCP 从不读取、存储或记录访问密钥或秘密。
在 AWS 模式下实现：
日志：CloudWatch Logs FilterLogEvents。
指标：CloudWatch GetMetricData（仅 MetricStat 查询）。
尚未实现：AWS 支持的部署和健康状态。未配置这些部分的服务只需为它们报告 NOT_CONFIGURED，与任何其他未配置的能力相同。参见 docs/aws.md 了解配置模式、分页行为和限制。
此集成的最低只读策略（虚构账户和日志组）：
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "logs:FilterLogEvents",
"Resource": "arn:aws:logs:us-east-1:123456789012:log-group:/aws/lambda/checkout-api"
},
{
"Effect": "Allow",
"Action": "cloudwatch:GetMetricData",
"Resource": "*"
}
]
}FilterLogEvents 可以限定到特定的日志组 ARN。对于此集成发出的 MetricStat 查询，GetMetricData 在 AWS 的 IAM 授权模型中没有资源级限定，因此该语句使用 Resource: "*"。这是 API 的属性，而非此处做出的选择。
资源 | 默认值 | 硬上限 |
列出的服务 | 50 | 200 |
日志事件 | 100 | 500 |
日志消息长度 | - | 2000 字符 |
日志/指标时间范围 | 1 小时 | 24 小时（日志），7 天（指标） |
每个系列的指标点 | - | 500 |
部署事件 | 20 | 100 |
每个服务的快照指标 | - | 5 |
每个有边界的结果都报告 requested_bounds 和 applied_bounds，以便调用者可以准确看到被限制的内容。将请求限制到硬上限与 PARTIAL 不同：一个被限制但完全满足的查询仍然是 SUCCESS。PARTIAL 意味着提取本身已知不完整，例如提供商分页并在耗尽应用窗口内的所有匹配项之前停止。
两个正交问题，绝不合并为一个：
此服务是否配置了该能力？（CONFIGURED / NOT_CONFIGURED）
如果已查询，发生了什么？（SUCCESS / EMPTY / PARTIAL / FAILED）
状态 | 含义 |
| 没有为此能力连接提供商。未尝试查询。 |
| 已查询提供商，提取已耗尽，没有匹配项。 |
| 已查询提供商并返回完整结果。 |
| 提取已知不完整。数据可能存在也可能不存在，例如到目前为止扫描的每个页面都是空的，但还有更多页面。 |
| 已查询提供商，但调用本身失败（超时、认证错误、速率限制）。 |
对于没有配置健康提供商的服务的健康检查是 NOT_CONFIGURED，而不是 EMPTY 也不是 FAILED。在时间窗口内合法地未找到任何内容的日志查询是 EMPTY，而不是 FAILED。在返回任何可用内容之前遇到速率限制的指标调用是 FAILED 并带有原因，而不是静默的空数据。
每个工具接受类型化参数并返回一个类型化的 Pydantic 模型。官方的 Python MCP SDK 直接从该返回类型派生 structuredContent 和工具的输出模式，工具响应是真正的结构化数据，而不是包裹在文本块中的 JSON 字符串。
flowchart TD
subgraph Providers
Fake[Fake providers]
AWS[AWS CloudWatch providers]
end
Fake --> Services
AWS --> Services
Registry[ServiceRegistry] --> Services
subgraph Services[Deterministic services]
Catalog[catalog_service]
Health[health_service]
Deploy[deployment_service]
Logs[logs_service]
Metrics[metrics_service]
Snapshot[snapshot_service]
end
Snapshot --> Deploy
Snapshot --> Logs
Snapshot --> Metrics
Snapshot --> Health
Services --> Tools[MCP tools]
Tools --> Agent[AI agent]get_operational_snapshot 组合原始服务，它不绕过它们或自行与提供商通信。参见 docs/architecture.md 获取完整的技术分解。
确定性的模拟场景端到端地测试完整的工具表面。
提供商层测试使用故意行为不当的存根提供商（错误排序、忽略边界）来证明服务层本身保护输出，而不仅仅是行为良好的提供商。
AWS 提供商测试使用小型存根 CloudWatch 客户端，没有真实的 AWS 调用，没有 moto，没有 LocalStack。
一个测试驱动真实的 MCP SDK 客户端与进程内服务器，确认协议边界本身（工具发现、结构化输出），而不仅仅是内部逻辑。
ruff check src tests
mypy src tests --strict
pytest -qAWS 实时验证已通过类型化配置解析、存根客户端测试和真实的 MCP 客户端/服务器边界完成，尚未针对真实的 AWS 账户进行。这需要用户选择的资源，并且有意不自动化：CloudOps MCP 不会自行发现或探测账户。
尚无 AWS 支持的部署或健康提供商。
仅 stdio 传输，无远程 MCP。
服务注册表是静态的且由配置支持，没有从云账户自动发现服务。
没有任何类型的修改、修复或写入路径。
现有提供商上的额外只读能力。
第二个真实提供商，以针对多个供应商压力测试标准化边界。
远程传输，如果部署场景确实需要的话。
被事件响应智能体消费，作为通用 MCP 客户端的一个示例。CloudOps MCP 不与任何特定消费者耦合。
提供者接口中没有任何变更方法。
不执行 shell 命令，不调用云 CLI 子进程。
最小权限 IAM：仅包含 logs:FilterLogEvents 和 cloudwatch:GetMetricData，不请求任何“以防万一”的权限。
仅使用标准 AWS 凭证链，不进行自定义凭证处理。
内部提供者引用（日志组名称、CloudWatch 维度）永远不会出现在工具输出中。
日志内容被视为不可信的不透明文本：从不解析、执行或解释。
意外失败在工具边界处被清理；只有固定的通用消息跨越该边界，绝不包含原始异常字符串。
每次遥测查询都有边界限制，既保护提供者 API，也保护代理的上下文窗口。
MIT，参见 LICENSE。
Get log events for a service, bounded by time range, count, and message length. Message content is opaque and never interpreted.
| Name | Required | Description | Default |
|---|---|---|---|
| service | Yes | ||
| max_events | No | ||
| time_range | No | ||
| environment | Yes |
| Name | Required | Description |
|---|---|---|
| capability | No | |
| collection | No | |
| availability | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It usefully discloses that message content is opaque and never interpreted and that results are bounded by count and message length (i.e., truncation behavior), but omits ordering, permissions, and, critically, what happens when time_range is null.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with the core operation front-loaded and zero filler; the opacity caveat follows the scope statement logically.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
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 explained. However, the absence of annotations and of any guidance on the required service/environment values or on the null-defaulted time_range leaves meaningful gaps for an agent to resolve.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage on the named properties is 0%, so the description must compensate. It loosely maps to time_range and max_events but gives no format or default semantics, and the two required parameters (service, environment) are undocumented in both schema and description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Get log events for a service') and names the dimensions it is bounded by (time range, count, message length). The resource is clearly distinguishable from siblings like get_metrics and get_service_health, though it never explicitly routes the agent against them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance, no prerequisites, and no mention of alternatives such as get_metrics or get_operational_snapshot for higher-level views. The bounding clauses describe limits, not when this tool is the right choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get metric series for a service. metric_names must be canonical names from get_services' available_metrics for that service. Always includes deterministic aggregates (min/max/average/last); raw points only when include_points=True, bounded.
| Name | Required | Description | Default |
|---|---|---|---|
| service | Yes | ||
| max_points | No | ||
| time_range | No | ||
| environment | Yes | ||
| metric_names | Yes | ||
| include_points | No |
| Name | Required | Description |
|---|---|---|
| capability | No | |
| collection | No | |
| availability | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does disclose output-shaping behavior: deterministic aggregates (min/max/average/last) are always returned, raw points only when include_points=True, and results are bounded. It says nothing about auth requirements, defaults for time_range, or rate limits, so it is strong but not complete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the core action and then the two key constraints; almost no filler. The trailing word 'bounded' is terse to the point of ambiguity about what bound applies.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so the description need not restate return fields, and it still usefully flags the conditional raw-points behavior. Given the 0% parameter coverage, it leaves time_range, service, and environment semantics undocumented, which is the main gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% across 6 parameters, so the description must compensate and only partially does: it explains metric_names (canonical names from get_services) and include_points, and hints at max_points via 'bounded'. service, environment, and time_range semantics (inclusive start / exclusive end, default) are left entirely to the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Get metric series for a service'), which naturally separates it from siblings like get_logs or get_service_health that operate on different resources. It is clear but never explicitly names a sibling or contrasting scope, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a concrete precondition: metric_names must be canonical names obtained from get_services' available_metrics, effectively telling the agent to call get_services first. It does not state when to prefer get_metrics over get_operational_snapshot or get_service_health, so no exclusions are covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a bounded operational snapshot for a service: recent deployments, its configured snapshot metrics, recent logs, and health. Each section reports its own status independently; a failure or unconfigured capability in one section never hides the others. Reports facts only, never a root cause.
| Name | Required | Description | Default |
|---|---|---|---|
| service | Yes | ||
| time_range | No | ||
| environment | Yes |
| Name | Required | Description |
|---|---|---|
| logs | Yes | |
| health | Yes | |
| metrics | Yes | |
| service | Yes | |
| deployments | Yes | |
| environment | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden, and it does meaningful work: each section reports status independently, a failure or unconfigured capability in one section never hides others, and it reports facts only, never root cause. These are genuinely useful operational traits. It still omits what 'bounded' means concretely, permission/auth requirements, and volume limits for logs and metrics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the purpose followed by two high-value behavioral notes. No filler, and each sentence adds information about scope or behavior rather than restating the name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-value explanation is not needed, and the description adequately covers purpose and partial-failure semantics. However, for an aggregation tool with three parameters and 0% schema coverage, the absence of parameter semantics and any guidance on choosing it over its four siblings leaves clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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, and it largely does not. 'for a service' gestures at the required service parameter, but environment, the optional time_range, and the default-null behavior are unexplained. The nested TimeRange carries its own schema description, but nothing in the tool description clarifies how parameters shape the snapshot.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (get an operational snapshot for a service) and enumerates the four content areas: deployments, metrics, logs, and health. This maps cleanly onto the four sibling tools, but the description never explicitly contrasts itself with those siblings (e.g., 'use this instead of calling get_logs/get_metrics separately'), so differentiation is implied rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The word 'bounded' hints at a scoped overview use case, but there is no explicit when-to-use, when-not-to-use, or mention of the sibling alternatives it aggregates. An agent cannot tell from the text whether to prefer this tool over get_recent_deployments + get_logs + get_metrics + get_service_health.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get recent deployment events for a service, bounded by time/count
| Name | Required | Description | Default |
|---|---|---|---|
| service | Yes | ||
| max_events | No | ||
| time_range | No | ||
| environment | Yes |
| Name | Required | Description |
|---|---|---|
| capability | No | |
| collection | No | |
| availability | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. 'Bounded by time/count' gestures at limiting behavior, but it never says what happens when time_range or max_events are omitted (both default to null), whether there is a server-side default window, or what the ordering/recency guarantee is. Read-only intent is only implied by the verb 'get'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler; the scope qualifier follows the core action. It is efficient, though 'bounded by time/count' is compressed to the point of ambiguity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-value documentation is not required, and the read-only nature of a 'get' tool is largely self-evident. Still, with zero annotations and two nullable tuning parameters, the description omits default-window behavior and the required environment parameter, leaving the agent to infer invocation semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 covers 'service' and loosely maps 'time/count' onto time_range and max_events, but the required 'environment' parameter is never mentioned and no defaults or format details are supplied (the UTC/inclusive-start semantics live only in the nested schema).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a clear verb (get) and resource (recent deployment events) plus scope (for a service, bounded by time/count), which distinguishes it from get_logs, get_metrics, and get_service_health. It does not name any sibling explicitly, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The word 'recent' hints at a use case, but there is no statement of when to prefer this over get_logs, get_metrics, or get_operational_snapshot, and no exclusions or prerequisites. An agent must infer everything about tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Provider-reported health signal for a service, never inferred
| Name | Required | Description | Default |
|---|---|---|---|
| service | Yes | ||
| environment | Yes |
| Name | Required | Description |
|---|---|---|
| capability | No | |
| collection | No | |
| availability | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden, and it does disclose one meaningful trait: the signal is provider-reported and never inferred, which tells the agent this is authoritative provenance rather than a derived heuristic. It still omits freshness, auth requirements, failure/unknown states, and error semantics for a tool whose entire value is a status signal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single clause, front-loaded with the resource and followed by the one qualifier that matters. Nothing is padded and nothing needs trimming.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
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 described, and the tool is structurally simple with only two params. Still, with zero annotations and zero parameter coverage, the definition leaves the agent without usage context or argument semantics, so it is only minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters (service, environment) have 0% schema description coverage, and the description adds no meaning — it does not clarify identifier format, environment naming, or whether defaults exist. For a 2-param required tool at zero coverage, the description should compensate and does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific resource (a service's health signal) and its provenance, so an agent can distinguish it from get_logs, get_metrics, or get_recent_deployments. However, there is no explicit verb and no named sibling to route against, so differentiation is implied rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as get_operational_snapshot or get_metrics. The agent is left to infer that this is the health-check counterpart to the other read tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List known services and which capabilities are configured for each.
| Name | Required | Description | Default |
|---|---|---|---|
| environment | No | ||
| max_services | No |
| Name | Required | Description |
|---|---|---|
| services | No | |
| truncated | No | |
| applied_max | Yes | |
| requested_max | Yes | |
| returned_count | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It implies a read-only list but does not state authentication requirements, pagination behavior, rate limits, or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler or redundancy. It is appropriately concise for a list operation, though its brevity contributes to gaps in other dimensions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
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 explained. However, with zero annotations and 0% parameter description coverage, the description omits filtering behavior (environment) and result limiting (max_services), leaving the agent without enough context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not mention the environment or max_services parameters at all. With 0% schema description coverage, it fails to compensate for the missing parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('List') and resource ('services') plus the returned data ('capabilities configured for each'). However, it does not differentiate from siblings such as get_operational_snapshot, so it misses the top score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance, prerequisites, or alternatives are named. Sibling tools like get_service_health or get_operational_snapshot are not referenced, leaving the agent to infer when this inventory tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0get_logsget_metricsget_operational_snapshotget_recent_deploymentsget_service_healthget_servicesScored across 6 tools
Each tool targets a distinct observability resource or action: service inventory, deployments, health, logs, metrics, and a composite snapshot. The composite snapshot is explicitly scoped as a bounded aggregation, so it does not blur with the individual tools. No two tools appear to do the same thing.
All six tools use the same get_ verb prefix and snake_case convention, with clear noun phrases (get_services, get_recent_deployments, get_service_health, get_logs, get_metrics, get_operational_snapshot). The pattern is predictable and easy to scan.
Six tools is a well-scoped size for a read-only CloudOps observability server. Each tool covers a distinct monitoring concern without redundant or filler endpoints.
The surface covers core operational data: services, deployments, health, logs, metrics, and a combined snapshot. Minor gaps exist for adjacent operational context such as alerts/incidents or deployment detail views, but core diagnostic workflows are supported.
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
The Cortex MCP server provides read-only access to real-time engineering context from the Cortex developer portal, allowing AI coding assistants to answer natural language questions about your organization's catalog (microservices, libraries, domains, teams, infrastructure), scorecards (engineering standards and best practices), initiatives (goals and deadlines), and Engineering Intelligence metrics. It includes tools for querying documentation, tracking personal entities, and accessing AI-assisted insights across the entire Cortex ecosystem.
