# Recipes

Ready-to-use MCP usage examples and AI conversation patterns.

## Listing and Filtering Data

### List All Records

```
User: "Show me all my projects"

AI calls: my_system_projects_list()

AI: "Here are your projects:
    1. Project Alpha (active)
    2. Project Beta (active)
    3. Project Gamma (archived)"
```

### Filter by Criteria

```
User: "Show me only active projects created this year"

AI calls: my_system_projects_list()
AI: [filters results by date and status]

AI: "Found 3 active projects created in 2026:
    1. Project Alpha (started Jan 15)
    2. Project Beta (started Feb 3)
    3. Project Gamma (started Mar 1)"
```

---

## Cross-System Queries

### Combine Data from Multiple Systems

```
User: "Compare the project list from System A with data from System B"

AI calls: system_a_projects_list()
AI calls: system_b_items_list(project_id="...")

AI: "Here's a summary:
    - Project Alpha: 5 open items (2 critical)
    - Project Beta: 12 items (all resolved)
    - Project Gamma: 3 open items"
```

---

## Creating and Updating Records

### Create a New Record

```
User: "Create a new item in the Alpha project with coordinates 60.17, 24.94"

AI calls: my_system_items_create(
    project_id="abc-123",
    coordinates=[60.17, 24.94],
    description="New survey point"
)

AI: "Created item at 60.17, 24.94 in Project Alpha.
    ID: item-456-789"
```

### Update Existing Data

```
User: "Update the description of item ITEM-123 to 'Resolved — issue fixed'"

AI calls: my_system_items_update(
    id="ITEM-123",
    description="Resolved — issue fixed"
)

AI: "Updated item ITEM-123 with new description."
```

> **Note:** Create and update operations require **Power mode** on your API key.

---

## Using Safe vs Power Mode

### Safe Mode (Read-Only)

Safe mode is the default. Agents can only read data:

```
User: "List all items"
AI calls: my_system_items_list()  ← Allowed

User: "Create a new item"
AI calls: my_system_items_create(...)  ← Blocked
AI: "I can't create items — my API key is in Safe mode.
    Ask your admin to switch to Power mode if you need write access."
```

### Power Mode (Full Access)

Power mode enables both read and write operations:

```
User: "Create a shipment"
AI calls: my_system_shipments_create(
    sender={...},
    receiver={...},
    packages=[{weight: 5.2, dimensions: "30x20x15"}]
)

AI: "Shipment created successfully. Tracking number: SH-2026-12345"
```

---

## Project-Scoped Access

### Working Within a Project

When your API key is bound to a project, only that project's systems are available:

```
User: "What tools do you have?"

AI: "I have access to tools for the Alpha project:
    - system_a_projects_list, system_a_projects_get
    - system_b_items_list, system_b_items_get
    - google_sheets_sheets_update"
```

### Listing Available Systems

```
User: "Which systems can I query?"

AI: "Based on my API key, I can access:
    1. System A — projects, items, reports
    2. System B — observations, inspections
    3. Google Sheets — spreadsheet data"
```

---

## Pagination and Large Datasets

### Fetching All Pages

```
User: "Get all items from the project — there might be thousands"

AI calls: my_system_items_list(
    project_id="abc-123",
    fetch_all_pages=true
)

AI: "Retrieved 2,847 items across 29 pages.
    Here's a summary by type:
    - Type A: 1,200
    - Type B: 1,647"
```

### Safety Limits

Automatic pagination has built-in safety limits:
- Maximum 100 pages per request
- Maximum 10,000 items
- 2-minute timeout
- Stops on empty or duplicate pages

---

## Audit and Monitoring

### Checking Recent Activity

```
User: "What API calls were made in the last hour?"

[Admin checks MCP Gateway → Audit Log in the UI]

Recent calls:
- my_system_projects_list (safe) — 200 OK — 12:05
- my_system_items_list (safe) — 200 OK — 12:08
- my_system_orders_create (power) — 201 Created — 12:15
```