Advanced Usage

MCP, Executors & Observability

Power-user features for extending Paean CLI with custom tools and debugging capabilities.

MCP Server Configuration

Paean CLI supports the Model Context Protocol (MCP) for extending agent capabilities with custom tools and data sources.

Configuration File

Add MCP servers to ~/.paean/mcp_config.json:

~/.paean/mcp_config.json

{
  "mcpServers": {
    "git": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-git"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://..."
      }
    }
  }
}

Popular MCP Servers

Server	Capabilities
@modelcontextprotocol/server-git	Git operations, diff, log
@modelcontextprotocol/server-filesystem	File read/write, directory listing
@modelcontextprotocol/server-postgres	Database queries, schema inspection
@modelcontextprotocol/server-slack	Slack messaging, channel access

Learn more: Model Context Protocol

Observability & Debugging

Trace and debug your agent's behavior with built-in observability tools.

Execution Traces

$ paean trace# List all traces

$ paean trace --latest# View latest execution

$ paean trace --report# Usage report

Trace Data Includes

•Full conversation history with timestamps
•Tool calls and their results
•Token usage and cost breakdown
•Error messages and stack traces
•Executor routing decisions

Configuration Files

Paean stores configuration and traces in ~/.paean/:

~/.paean/
├── config.json      # Auth and preferences
├── mcp_config.json  # MCP server configuration
└── traces/          # Execution logs and debug data

Pro Tips

🔗 Chain Complex Workflows

Use --chain for dependent multi-step operations.

paean prompt "lint, then fix errors, then commit" --chain

⚡ Force Specific Executors

Override auto-routing when you know which executor works best.

paean prompt "refactor auth" --executor cursor

🔄 Auto-validate Changes

Automatically mark completed tasks based on git changes.

paean validate --auto-complete