notion-mcp: Instructions file for Codex

Agent Specification: Notion Terminal MCP

Technical specification and operational guide for AI Agents (Notion Custom Agents, Claude, Cursor, Antigravity, and autonomous LLM agents) interacting with this MCP server.

---

1. System Overview

• Server Identifier: notion-terminal-files
• Protocol: Model Context Protocol (MCP)
• Transports: Streamable HTTP (/mcp) & Standard SSE (/sse + /messages)
• Health Check: GET /health
• Server Info: GET /
• Authentication: HTTP Authorization header (Authorization: Bearer <API_KEY>) or x-api-key: <API_KEY>

┌────────────────────────────────────────┐
│        AI Agent (e.g. Notion)          │
└───────────────────┬────────────────────┘
                    │  Streamable HTTP (JSON-RPC / MCP)
                    ▼
┌────────────────────────────────────────┐
│     Ngrok / Cloudflare Public Tunnel   │
└───────────────────┬────────────────────┘
                    │
┌───────────────────▼────────────────────┐
│      Notion Terminal MCP Server        │
│  - Timing-Safe Authentication          │
│  - Host Header Validation              │
│  - Sandboxed / Full Access FS          │
│  - UTF-8 Windows Console Integration   │
│  - Structured Audit Logging            │
└────────────────────────────────────────┘

---

2. Security & Execution Model

2.1 Sandboxing (FULL_ACCESS)

• When FULL_ACCESS=false (Default Sandbox):
  • All file and directory paths are strictly jailed within FILES_ROOT (e.g., ./workspace or custom configured path).
  • Path traversal attempts (../, symlink escapes, absolute paths pointing outside FILES_ROOT) are immediately rejected with an error.
  • Working directories (cwd) for terminal_execute default to FILES_ROOT.
• When FULL_ACCESS=true (Unrestricted Mode):
  • The agent has full access to the host filesystem with permissions of the host user running the server.

2.2 Limits and Buffers

• MAX_OUTPUT_BYTES (default: 1 MB): Terminal output exceeding this limit is capped with truncated: true.
• MAX_FILE_BYTES (default: 10 MB): File read/write operations exceeding this limit require offset pagination or are rejected.
• COMMAND_TIMEOUT_MS (default: 120,000 ms, max: 900,000 ms): Long running processes are automatically killed with their full process tree.