Skip to content

API Reference

This document provides the API reference for the AWS Logs MCP server.

Endpoints

The MCP server exposes the following endpoints:

Endpoint Method Description
/sse GET Server-Sent Events endpoint for MCP communication
/mcp POST Direct endpoint for MCP tool invocations
/health GET Health check endpoint

MCP Protocol

AWS Logs MCP implements the Model Context Protocol for AI assistant integration.

Tool Registration

When a client connects, the server registers available tools:

{
  "type": "tool_registration",
  "tools": [
    {
      "name": "cloudWatchLogGroups",
      "description": "List available CloudWatch Log Groups with optional filtering",
      "schema": {
        "type": "object",
        "properties": {
          "prefix": {
            "type": "string",
            "description": "Filter log groups by prefix"
          },
          "limit": {
            "type": "number",
            "description": "Maximum number of log groups to return"
          }
        }
      }
    },
    // Other tools...
  ]
}

Tool Invocation

Clients invoke tools using:

{
  "type": "tool_invocation",
  "id": "invocation-123",
  "name": "cloudWatchLogs",
  "params": {
    "logGroupName": "/aws/lambda/my-function",
    "startTime": "-1h",
    "limit": 50
  }
}

Tool Response

The server responds with:

{
  "type": "tool_response",
  "id": "invocation-123",
  "status": "success",
  "content": [
    {
      "type": "text",
      "text": "[2023-01-15T12:34:56.789Z] Log message content..."
    }
  ]
}

Error Response

For errors, the server responds with:

{
  "type": "tool_response",
  "id": "invocation-123",
  "status": "error",
  "error": {
    "type": "AWS_SERVICE_ERROR",
    "message": "Failed to retrieve logs: Access denied",
    "service": "CloudWatchLogs",
    "operation": "filterLogEvents"
  }
}

Health Check

The /health endpoint returns information about server health:

{
  "status": "healthy",
  "version": "1.0.0",
  "uptime": 3600,
  "timestamp": "2023-01-15T12:34:56.789Z",
  "aws": {
    "connectivity": true,
    "region": "us-east-1"
  },
  "memory": {
    "rss": 75000000,
    "heapTotal": 50000000,
    "heapUsed": 40000000
  }
}

Direct MCP Endpoint

The /mcp endpoint accepts direct POST requests:

Request:

{
  "tool": "cloudTrailEvents",
  "params": {
    "eventName": "CreateFunction",
    "startTime": "-1d",
    "limit": 25
  }
}

Response:

{
  "status": "success",
  "content": [
    {
      "type": "text",
      "text": "[JSON string with CloudTrail events]"
    }
  ]
}

Error Codes

Error Code HTTP Status Description
VALIDATION_ERROR 400 Invalid parameters
AUTHENTICATION_ERROR 401 AWS authentication failed
PERMISSION_ERROR 403 Insufficient AWS permissions
RESOURCE_NOT_FOUND 404 Requested resource not found
AWS_SERVICE_ERROR 502 AWS service error
INTERNAL_ERROR 500 Server internal error