Notion Dev Containers MCP - Agent Instructions

This document provides comprehensive guidance for AI agents on how to use the Notion Dev Containers MCP (Model Context Protocol) server effectively.

---

Overview

The notion-dev-containers MCP server provides tools for managing containerized Notion services running via Podman/Docker. It enables agents to:

• Monitor container status and health
• View and search container logs
• Start, stop, and restart services
• Execute commands inside containers
• Manage the entire container stack

---

Available Services

The MCP server manages the following containerized services:

| Service | Container Name | Port | Description | |---------|---------------|------|-------------| | polling | notion-polling | 8080 | Polls Notion API for changes, syncs to MSSQL | | api | notion-api | 8000 | FastAPI REST service for write operations | | archival-grpc | notion-archival-grpc | 50051 (gRPC) | gRPC server for archival operations | | notion-sync | notion-sync | 50054 (gRPC) | Queue worker for sync operations | | notion-jit | notion-jit | 50055 (gRPC) | JIT (Just-In-Time) refresh service | | gateway | gateway | 8000 | FastAPI gateway service | | nginx-gateway | nginx-gateway | 80 | Nginx reverse proxy | | redis | notion-redis | 6379 | Redis cache for gateway | | stonepro-service | stonepro-service | 8080 | StonePro ERP integration |

---

Tool Reference

1. Monitoring & Status Tools

list_services

Lists all services and their current status at a glance.

Parameters: None

Use when: You need a quick overview of which containers are running, stopped, or have errors.

Example output:

# Notion Container Services Status

## 🟢 Running
- **polling** (notion-polling): ✅ healthy
- **api** (notion-api): ✅ healthy

## 🔴 Stopped
- **redis** (notion-redis): exited

## ⚪ Not Found
- **gateway** (gateway): container not created

---

service_status

Get detailed status for a specific service including health, ports, and resource usage.

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | service | string | ✅ | Service name (see Available Services table) |

Use when: You need deep diagnostic info about a specific service—its health state, uptime, port mappings, and CPU/memory usage.

---

health_check_all

Run health checks on all services and return a summary.

Parameters: None

Use when: You want to quickly determine the overall health of the container stack without needing port or resource details.

Example output:

# Health Check Summary

**Summary:** 5 healthy, 2 unhealthy, 2 unknown

🟢 **polling**: healthy
🟢 **api**: healthy
🔴 **redis**: stopped
⚪ **gateway**: not deployed

---

get_resource_usage

Get CPU and memory usage for a specific service.

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | service | string | ✅ | Service name |

Use when: You need to check if a service is consuming excessive resources or to diagnose performance issues.

Example output:

# Resource Usage: polling

- **CPU:** 2.34%
- **Memory:** 156.2MiB / 2GiB (7.62%)
- **Network I/O:** 1.2MB / 456KB
- **Block I/O:** 12MB / 4MB

---

2. Log Tools

get_logs

Get logs from a container service with optional filtering.

Parameters: | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | service | string | ✅ | - | Service name | | lines | integer | ❌ | 100 | Number of log lines to retrieve | | filter | string | ❌ | - | Regex pattern to filter logs | | since | string | ❌ | - | Show logs since timestamp (e.g., 10m, 1h, 2024-01-01) |

Use when: You need to inspect logs from a specific service, especially when debugging issues.

Best practices:

• Start with lines: 50 for quick checks
• Use filter with regex like "error|exception|failed" to find problems
• Use since: "10m" to focus on recent activity

---

search_logs

Search logs across multiple services for a pattern.

Parameters: | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | pattern | string | ✅ | - | Regex pattern to search for | | services | array | ❌ | all | List of services to search | | lines | integer | ❌ | 500 | Lines to search per service |

Use when: You need to find occurrences of errors, warnings, or specific events across the entire stack.

Example patterns:

• "error|exception" - Find all errors
• "request.*failed" - Find failed requests
• "notion.*api" - Find Notion API related logs
• "status.*5[0-9]{2}" - Find HTTP 5xx errors

---

3. Service Control Tools

start_service

Start a stopped container service.

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | service | string | ✅ | Service name to start |

Use when: A service is stopped and needs to be started.

---

stop_service

Stop a running container service.

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | service | string | ✅ | Service name to stop |

Use when: You need to gracefully stop a service (e.g., before maintenance or to free resources).

---

restart_service

Restart a container service.

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | service | string | ✅ | Service name to restart |

Use when: A service is behaving unexpectedly and needs a fresh start, or after configuration changes.

---

rebuild_service

Rebuild a service's container image.

Parameters: | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | service | string | ✅ | - | Service name to rebuild | | no_cache | boolean | ❌ | false | Build without using cache |

Use when: Code changes have been made and the container image needs to be rebuilt. Use no_cache: true if you suspect caching issues.

⚠️ Note: Rebuilding takes time. The service will be unavailable during the rebuild.

---

4. Compose Management Tools

compose_up

Start all services using podman-compose.

Parameters: | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | detach | boolean | ❌ | true | Run in detached mode |

Use when: You need to bring up the entire container stack at once.

---

compose_down

Stop and remove all containers.

Parameters: | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | volumes | boolean | ❌ | false | Also remove volumes |

Use when: You need to tear down the entire stack. Use volumes: true only if you want to clear all persisted data.

⚠️ Caution: Using volumes: true will delete all data in container volumes!

---

5. Container Interaction Tools

exec_command

Execute a command inside a running container.

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | service | string | ✅ | Service name | | command | string | ✅ | Shell command to execute |

Use when: You need to run diagnostic commands, check file contents, or interact with the container's internal environment.

Example commands:

• ls -la /app - List application files
• cat /app/config.py - View configuration
• pip list - List installed Python packages
• env | grep NOTION - Check Notion-related env vars
• ps aux - View running processes
• df -h - Check disk usage

---

get_env

Get environment variables from a running container (sensitive values are masked).

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | service | string | ✅ | Service name |

Use when: You need to verify environment configuration. Note that values containing "password", "secret", "key", or "token" are automatically masked for security.

---

get_ports

Get port mappings for a service.

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | service | string | ✅ | Service name |

Use when: You need to know which host ports are mapped to a container's internal ports.

---

Common Workflows

Debugging a Service Issue

1. Check overall status:

   list_services
   

2. Get detailed status for the problematic service:

   service_status(service: "polling")
   

3. Check recent logs for errors:

   get_logs(service: "polling", lines: 100, filter: "error|exception|failed")
   

4. If needed, restart the service:

   restart_service(service: "polling")
   

Finding Errors Across All Services

1. Search all logs for errors:

   search_logs(pattern: "error|exception|traceback", lines: 500)
   

2. Narrow down to specific services if needed:

   search_logs(pattern: "connection refused", services: ["api", "gateway"])
   

Deploying Code Changes

1. Rebuild the affected service:

   rebuild_service(service: "api", no_cache: false)
   

2. Restart to pick up changes:

   restart_service(service: "api")
   

3. Verify it's healthy:

   service_status(service: "api")
   

Starting Fresh

1. Tear everything down:

   compose_down(volumes: false)
   

2. Bring everything up:

   compose_up(detach: true)
   

3. Verify health:

   health_check_all
   

Investigating Resource Issues

1. Check resource usage:

   get_resource_usage(service: "archival-grpc")
   

2. If high CPU, check what's running:

   exec_command(service: "archival-grpc", command: "ps aux | head -20")
   

---

Error Handling

Container Runtime Unavailable

If you see "Container runtime unavailable" or similar errors:

1. On Windows: The Podman VM may not be running. The user needs to run:

   podman machine start
   

2. Check if Podman is installed: The runtime might not be installed at all.

Service Not Found

If a service shows as "not found":

• The container hasn't been created yet
• Run compose_up to create all containers

Compose Command Failures

If compose commands fail with "command not found":

• podman-compose may not be installed
• The user can either install it (pip install podman-compose) or set COMPOSE_CMD=podman compose

---

Environment Variables

The MCP server behavior can be customized via environment variables:

| Variable | Default | Description | |----------|---------|-------------| | CONTAINER_RUNTIME | podman | Container runtime (podman or docker) | | COMPOSE_CMD | podman compose (Windows) / podman-compose (Linux) | Compose command | | COMPOSE_FILE | podman-compose.yml | Compose file name | | MCP_CONTAINER_CMD_TIMEOUT | 10 | Timeout for container commands (seconds) | | MCP_COMPOSE_TIMEOUT | 120 | Timeout for compose commands (seconds) |

---

Best Practices for Agents

1. Always start with list_services or health_check_all to understand the current state before taking action.

2. Use filtered log queries instead of fetching thousands of lines—be specific with regex patterns.

3. Check status after actions - After starting, stopping, or restarting a service, verify with service_status.

4. Be cautious with compose_down(volumes: true) - This deletes all persistent data.

5. Use search_logs for cross-service debugging - It's more efficient than checking each service individually.

6. Mask sensitive data - The get_env tool masks passwords automatically, but be careful when using exec_command with commands that might expose secrets.

7. Timeouts - Compose operations can take time (up to 120 seconds). Be patient with compose_up and rebuild_service.

---

Quick Reference Card

| Task | Tool | Key Parameters | |------|------|----------------| | See all service states | list_services | - | | Deep-dive one service | service_status | service | | Quick health check | health_check_all | - | | View logs | get_logs | service, lines, filter | | Search all logs | search_logs | pattern, services | | Start service | start_service | service | | Stop service | stop_service | service | | Restart service | restart_service | service | | Rebuild image | rebuild_service | service, no_cache | | Run command in container | exec_command | service, command | | Check env vars | get_env | service | | Check ports | get_ports | service | | Check resources | get_resource_usage | service | | Start all services | compose_up | detach | | Stop all services | compose_down | volumes |