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

Check overall status:
```
list_services
```
Get detailed status for the problematic service:
```
service_status(service: "polling")
```

Check recent logs for errors:

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

If needed, restart the service:
```
restart_service(service: "polling")
```

Finding Errors Across All Services

Search all logs for errors:

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

Narrow down to specific services if needed:

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

Deploying Code Changes

Rebuild the affected service:

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

Restart to pick up changes:
```
restart_service(service: "api")
```
Verify it's healthy:
```
service_status(service: "api")
```

Starting Fresh

Tear everything down:
```
compose_down(volumes: false)
```
Bring everything up:
```
compose_up(detach: true)
```
Verify health:
```
health_check_all
```

Investigating Resource Issues

Check resource usage:

get_resource_usage(service: "archival-grpc")

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:

On Windows: The Podman VM may not be running. The user needs to run:
```
podman machine start
```
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

Always start with list_services or health_check_all to understand the current state before taking action.
Use filtered log queries instead of fetching thousands of lines—be specific with regex patterns.
Check status after actions - After starting, stopping, or restarting a service, verify with service_status.
Be cautious with compose_down(volumes: true) - This deletes all persistent data.
Use search_logs for cross-service debugging - It's more efficient than checking each service individually.
Mask sensitive data - The get_env tool masks passwords automatically, but be careful when using exec_command with commands that might expose secrets.
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 |

notion-archive-container-mcp

Notion Dev Containers MCP - Agent Instructions

Overview

Available Services

Tool Reference

1. Monitoring & Status Tools

list_services

service_status

health_check_all

get_resource_usage

2. Log Tools

get_logs

search_logs

3. Service Control Tools

start_service

stop_service

restart_service

rebuild_service

4. Compose Management Tools

compose_up

compose_down

5. Container Interaction Tools

exec_command

get_env

get_ports

Common Workflows

Debugging a Service Issue

Finding Errors Across All Services

Deploying Code Changes

Starting Fresh

Investigating Resource Issues

Error Handling

Container Runtime Unavailable

Service Not Found

Compose Command Failures

Environment Variables

Best Practices for Agents

Quick Reference Card

`list_services`

`service_status`

`health_check_all`

`get_resource_usage`

`get_logs`

`search_logs`

`start_service`

`stop_service`

`restart_service`

`rebuild_service`

`compose_up`

`compose_down`

`exec_command`

`get_env`

`get_ports`