---
title: MCP Model Explorer
amsdal_docs:
  target: framework/plugins/amsdal-ml/mcp-model-explorer.md
  nav_title: Model Explorer
  nav_section: Framework
  nav_path: ["Plugins & Extensions", "ML", "MCP Server"]
  nav_order: 2
---

# MCP Model Explorer

The Model Explorer is the HTTP/SSE MCP server that lets AI assistants discover, inspect, and operate on your AMSDAL models via natural language.

## Available Tools

### list_available_models

Discover all registered AMSDAL models with their fields and relationships.

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `scope` | `str \| None` | Optional filter by scope: `core`, `contrib`, or `user` |

**Returns** a list of models with:
- Model name
- Field names
- Foreign key relationships

### list_available_transactions

Lists all available AMSDAL transactions. Use this to discover executable transactions before running one.

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `scope` | `str` | Filter by scope: `all` (default), `user` (custom user-defined), or `contrib` (system-level/shared) |

**Returns** a catalog of transactions with their name, description, scope, and parameter types.

### get_model_schema

Get the full JSON Schema for a specific model, including computed properties.

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `model_name` | `str` | Name of the AMSDAL model |

**Returns** the complete JSON Schema with field types, constraints, defaults, and computed properties.

### get_model_relationships

Inspect a model's foreign key graph — both outgoing (many-to-one) and incoming (one-to-many) relationships.

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `model_name` | `str` | Name of the AMSDAL model |

**Returns** outgoing and incoming relationship details with field names, target models, and cardinality.

### perform_crud_operation

Execute CRUD operations using natural language with a two-step confirmation flow.

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `model_name` | `str` | Name of the AMSDAL model |
| `operation` | `str` | One of: `read`, `create`, `update`, `delete` |
| `query` | `str` | Natural language description of the operation |
| `confirm` | `bool` | Set to `true` to execute after preview (default `false`) |
| `preview_limit` | `int` | Max records to show in preview (default `5`) |
| `limit` | `int \| None` | Max records to return (default `30`) |
| `analysis` | `dict \| None` | Analysis from step 1, passed back in step 2 (default `None`) |

**Two-step flow:**

1. First call with `confirm=false` — returns a preview with an `analysis` dict
2. Second call with `confirm=true` and the `analysis` from step 1 — executes the operation

This prevents accidental data modifications through AI assistants.

### perform_transaction_operation

Executes AMSDAL transactions from natural language descriptions using a mandatory two-step confirmation flow. The raw query is passed to an AI planner that maps arguments (primitives, model references, or new objects) to the expected transaction parameters.

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `transaction_name` | `str` | Name of the AMSDAL transaction |
| `query` | `str` | Raw natural language description of the operation exactly as typed by the user |
| `confirm` | `bool` | Set to `true` to execute after preview (default `false`) |
| `preview_limit` | `int` | Max records to show in preview for reference searches (default `5`) |
| `analysis` | `dict \| None` | Analysis from step 1, passed back in step 2 (default `None`) |

**Two-step flow:**

1. First call with `confirm=false` — returns a preview mapping with an `analysis` dict showing how arguments were parsed.
2. Second call with `confirm=true` and the `analysis` from step 1 — executes the transaction.

## Example Conversation

A typical conversation with an AI assistant connected via MCP:

> **User:** What models are available?
>
> *Assistant calls `list_available_models`*
>
> **Assistant:** You have Customer, Order, Product, and Invoice models.
>
> **User:** Update John Doe's email to john@new.com
>
> *Assistant calls `perform_crud_operation(model_name='Customer', operation='update', query='update John Doe email to john@new.com', confirm=false)`*
>
> **Assistant:** This will change John Doe's email from john@old.com to john@new.com. Confirm?
>
> **User:** Yes
>
> *Assistant calls with `confirm=true`*
>
> **User:** Are there any custom actions I can perform?
>
> *Assistant calls `list_available_transactions(scope='user')`*
>
> **Assistant:** Yes, you can run the `apply_discount` transaction.
>
> **User:** Apply a 10% discount to John Doe's last order.
>
> *Assistant calls `perform_transaction_operation(transaction_name='apply_discount', query='Apply a 10% discount to John Doe\\'s last order', confirm=false)`*
>
> **Assistant:** This will run the `apply_discount` transaction mapping John Doe's last order to the `order` parameter and `10` to the `percentage` parameter. Confirm?
>
> **User:** Yes
>
> *Assistant calls `perform_transaction_operation(..., confirm=true, analysis=...)`*

## Row-Level Filtering

The Model Explorer uses `api_objects` manager, which applies row-level permissions automatically. Users only see and modify records they're authorized to access.
