Content
# OpenSearch MCP Server for AWS DevOps Agent
A self-hosted [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server designed for [AWS DevOps Agent](https://aws.amazon.com/devops-agent/), connecting it to OpenSearch clusters in your VPC for log search, monitoring, and cluster operations.
## Architecture
```
AI Agent → API Gateway + Cognito OAuth 2.1 → Lambda (VPC) → OpenSearch (VPC)
```
```mermaid
sequenceDiagram
participant Agent as AI Agent
participant APIGW as API Gateway
participant Cognito as Cognito
participant Lambda as Lambda (VPC)
participant OS as OpenSearch (VPC)
Agent->>APIGW: POST /mcp (no auth)
APIGW-->>Agent: 401 Unauthorized
Note over Agent: MCP_SERVER_REACHABLE_WITH_AUTH ✅
Agent->>Cognito: POST /oauth2/token (client_credentials)
Cognito-->>Agent: Bearer token (JWT)
Agent->>APIGW: POST /mcp (Bearer token)
APIGW->>APIGW: Cognito Authorizer validates JWT
APIGW->>Lambda: Forward request
Lambda->>OS: Query/Ingest
OS-->>Lambda: Results
Lambda-->>APIGW: MCP JSON-RPC response
APIGW-->>Agent: 200 OK
```
## Available Tools (13)
### Log Operations
| Tool | Description |
|------|-------------|
| `search_logs` | Search logs by keyword and/or time range (ISO8601) |
| `get_recent_logs` | Get most recent N log entries |
| `get_log_stats` | Log statistics — count by level, top sources |
| `ingest_log` | Ingest a log entry (for testing) |
### Cluster Operations
| Tool | Description |
|------|-------------|
| `cluster_health` | Cluster health status (green/yellow/red), node and shard counts |
| `list_indices` | List all indices with doc count, size, health |
| `get_index_mapping` | Retrieve index mapping and settings |
| `get_shards` | Shard allocation info (primary/replica, state, node) |
| `cat_nodes` | Node info: CPU, memory, disk, roles |
### Index & Task Operations
| Tool | Description |
|------|-------------|
| `count_documents` | Document count, optionally filtered by query |
| `get_index_stats` | Index performance stats (indexing/search rate, store size) |
| `get_allocation` | Shard allocation across nodes (disk usage per node) |
| `get_long_running_tasks` | Long-running tasks sorted by duration |
## Deploy
### Prerequisites
- AWS CLI configured
- An AWS account with permissions for CloudFormation, Lambda, API Gateway, Cognito, OpenSearch
### One-command deployment
```bash
aws cloudformation create-stack \
--stack-name mcp-opensearch \
--template-body file://cfn-template.yaml \
--capabilities CAPABILITY_IAM \
--region us-east-1
```
OpenSearch cluster creation takes ~15 minutes.
### Get credentials after deployment
```bash
# Get stack outputs
aws cloudformation describe-stacks --stack-name mcp-opensearch \
--query 'Stacks[0].Outputs' --output table --region us-east-1
# Get Cognito client secret
USER_POOL_ID=$(aws cloudformation describe-stacks --stack-name mcp-opensearch \
--query 'Stacks[0].Outputs[?OutputKey==`UserPoolId`].OutputValue' --output text --region us-east-1)
CLIENT_ID=$(aws cloudformation describe-stacks --stack-name mcp-opensearch \
--query 'Stacks[0].Outputs[?OutputKey==`ClientId`].OutputValue' --output text --region us-east-1)
aws cognito-idp describe-user-pool-client --user-pool-id $USER_POOL_ID \
--client-id $CLIENT_ID --query 'UserPoolClient.ClientSecret' --output text --region us-east-1
```
### Customize
| Parameter | Required | Description | Example |
|-----------|----------|-------------|---------|
| `VpcId` | Yes | VPC for OpenSearch and Lambda | `vpc-0abc1234def56789` |
| `SubnetIds` | Yes | At least 2 subnets in different AZs | `subnet-aaa111,subnet-bbb222` |
| `OpenSearchMasterUser` | No | OpenSearch master username (default: `admin`) | `admin` |
| `OpenSearchMasterPassword` | Yes | OpenSearch master password | `MyP@ssw0rd!` |
| `LambdaS3Bucket` | Yes | S3 bucket containing Lambda zip | `my-lambda-bucket` |
## Test
```bash
# Get token
TOKEN=$(curl -s -X POST "$TOKEN_ENDPOINT" \
-H "Content-Type: application/x-www-form-urlencoded" \
-u "$CLIENT_ID:$CLIENT_SECRET" \
-d "grant_type=client_credentials&scope=mcp-api/invoke" \
| python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])")
# Handshake (expect 401)
curl -s -o /dev/null -w "%{http_code}" -X POST "$MCP_ENDPOINT" \
-H "Content-Type: application/json" -d '{}'
# Initialize
curl -s -X POST "$MCP_ENDPOINT" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'
# List tools
curl -s -X POST "$MCP_ENDPOINT" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
# Call a tool
curl -s -X POST "$MCP_ENDPOINT" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"cluster_health","arguments":{}}}'
```
## Update Lambda Code
After modifying `index.py`, re-run the deploy script:
```bash
./deploy.sh
```
## Register with AWS DevOps Agent
| Field | Value |
|-------|-------|
| Endpoint URL | `https://<api-id>.execute-api.<region>.amazonaws.com/prod/mcp` |
| Auth Type | OAuth 2.1 - Client Credentials |
| Client ID | *(from stack output)* |
| Client Secret | *(from cognito-idp describe-user-pool-client)* |
| Token URL | `https://mcp-opensearch-<account>.auth.<region>.amazoncognito.com/oauth2/token` |
| Scope | `mcp-api/invoke` |
## Test Prompt
After registering with DevOps Agent, try this prompt to verify all tools work end-to-end:
```
First, ingest a few test log entries: one ERROR about "database connection timeout",
one WARN about "high memory usage at 92%", and one INFO about "deployment completed
successfully". Use the mcp-opensearch-logs server.
Then search for any error logs, and give me the log statistics for the last 60 minutes.
```
The agent will call 5 tools: 3× `ingest_log`, 1× `search_logs`, 1× `get_log_stats`.
## License
MIT
