# 4D MCP MCP

> 4D MCP connects your 4D database directly to your AI client. This lets your agent explore data structures, query tables, and manage records without you writing a single REST call. You can audit catalogs, run complex lookups across defined data classes, and perform high-speed CRUD operations entirely through conversation.

## Overview
- **Category:** developer-tools
- **Price:** Free
- **Tags:** database-management, orda, rest-api, data-querying, entity-management, application-development

## Description

Your 4D database is designed for structure. When working with it traditionally, you're stuck in the world of manual API calls—writing boilerplate code just to figure out what tables exist or how to format a single record update. This MCP changes that. It treats your entire data layer like an intelligent knowledge base. Your agent can now talk to your database naturally; it doesn't need specific instructions for every field or table. You simply ask, and the system figures out the right operation. Because Vinkius hosts this integration, you get instant access to advanced query capabilities alongside basic entity management. You treat querying complex data like talking to a coworker who already knows where everything is stored.

## Tools

### delete_entity
Removes an entire record from a specified database table.

### list_entities
Queries multiple records from a table, supporting advanced filters and sorting rules.

### get_entity
Fetches one specific record from a table using its unique primary key ID.

### create_entity
Adds a brand new record to the database table when given the necessary data payload.

### update_entity
Changes the data within an existing record by accepting new field values.

### get_catalog
Retrieves the full structural map of your database, listing all available tables and their fields.

## Prompt Examples

**Prompt:** 
```
Show me the first 5 records from the 'Invoices' table.
```

**Response:** 
```
I've retrieved the first 5 invoices from your 4D database. Here are the details including IDs, amounts, and dates.
```

**Prompt:** 
```
What tables (DataClasses) are exposed in my 4D catalog?
```

**Response:** 
```
I've explored your 4D catalog. You have the following DataClasses available: Invoices, Customers, Products, and Orders. Which one would you like to query?
```

**Prompt:** 
```
Create a new record in the 'Customers' table for 'John Doe' with email 'john@example.com'.
```

**Response:** 
```
I've successfully created the new customer record for John Doe in your 4D database. The record is now live and assigned a new primary key.
```

## Capabilities

### Discover Data Structures
Retrieve the full list of available tables and their specific fields so you can map out your entire data model.

### Query Specific Records
Fetch a single, identified record by its primary key for quick lookups.

### Run Complex Data Searches
Perform advanced searches across an entire table using filters, sorting rules, and joining related data.

### Create New Entries
Add entirely new records into any exposed database table.

### Modify Existing Data
Update the content of a record, changing specific fields without touching the rest of the data.

### Remove Records
Permanently delete records from the database when they are no longer needed.

## Use Cases

### Auditing Data Integrity
A developer needs to verify if all records in the 'Orders' table have a corresponding entry in the 'Customers' table. The agent first calls `get_catalog` to confirm the tables, then uses `list_entities` with complex filtering logic to identify missing foreign keys.

### Generating Quarterly Reports
A data analyst needs a list of all 'Products' that were modified in Q1. They ask the agent, and it executes a filtered search using `list_entities` based on modification dates, pulling exactly the subset they need.

### Onboarding New Users
A business admin has to create a new employee profile across three linked tables (User, Department, Contact). The agent manages this by calling `create_entity` sequentially for each required record, guaranteeing the primary keys link up correctly.

### Debugging Application State
A QA engineer needs to see exactly what data is tied to a specific test case. They ask the agent to retrieve the full 'TestRun' entity using `get_entity`, instantly showing all related logs and metrics.

## Benefits

- Instead of writing custom code for every query, simply ask the agent to use `list_entities` with filters like '$filter'—it handles the complex ORDA syntax automatically. It’s a huge time saver.
- Need to know what data structures you even have? Use `get_catalog`. It immediately gives you a full map of every table and field, saving you hours of schema investigation.
- When your agent needs to make changes, it can use `create_entity` or `update_entity`. You don't need separate API endpoints for writes; the MCP handles it all in one flow.
- Forget writing complex manual lookups. The tool allows advanced querying via `list_entities`, letting you search and sort records using natural language parameters like date ranges or status flags.
- If a record is wrong, deleting it shouldn't be a process nightmare. You can use `delete_entity` right through the chat interface to clean up data without touching deployment code.

## How It Works

The bottom line is, you tell your agent what you want; it figures out how to talk to the 4D database and gets it for you.

1. Subscribe to this MCP and provide your 4D Base URL credentials.
2. Direct your AI agent's attention to this MCP within any compatible client.
3. Ask the agent a question (e.g., 'Show me all orders for John Doe'). The agent handles the necessary operations in the background.

## Frequently Asked Questions

**How does the 4D MCP work for listing all data?**
It uses the `list_entities` tool. You don't need to know complex ORDA syntax; you just tell your agent what table and what filters you want, and it handles the rest of the advanced querying.

**Can I use 4D MCP to check my database structure?**
Yes. You simply ask the agent to look at the catalog, which triggers the `get_catalog` tool. It'll give you a full list of all available tables and their field definitions.

**What if I only need one specific record? Should I use get_entity or list_entities?**
If you have the unique primary key, use `get_entity`. It’s faster. If you need to search for a record based on criteria (like 'email address'), then you should use `list_entities`.

**Is 4D MCP safe for writing data?**
Yes, it's designed for controlled writes. Operations like creating or updating records are managed by the agent using tools such as `create_entity` and `update_entity`, ensuring consistency with your schema.

**When I need to create or modify data, what format does `create_entity` require for the payload?**
It requires a JSON string representing the data. Make sure your JSON keys and values match the DataClass schema you first check using `get_catalog`. This ensures type safety when writing records.

**If I'm querying a massive dataset, how does `list_entities` handle pagination or performance? **
The tool supports ORDA-style parameters like `$filter` and `$orderby`, letting you narrow down the search results. Always filter your request instead of trying to pull records without limits.

**If I run several write commands, such as `delete_entity` followed by an `update_entity`, are they treated as a single transaction?**
No, the MCP executes each tool call independently. If you need to guarantee data integrity across multiple actions, your client logic must handle those steps sequentially.

**Does using `get_catalog` or any other tool require me to manage API rate limits?**
Vinkius handles the connection management and throttling for you. You don't need to worry about hitting specific 4D server rate limits; your AI client manages the calls.

**How do I find which tables are available?**
Use the `get_catalog` tool. It will return a list of all DataClasses (tables) exposed through the REST API in your 4D Server.

**Can I filter data based on specific conditions?**
Yes. Use the `list_entities` tool and provide an ORDA-style filter string in the `$filter` parameter (e.g., "status = 'active' AND price > 100").

**Does this support creating new records?**
Absolutely. Use the `create_entity` tool by providing the DataClass name and a JSON string containing the field data for the new record.