Table Management
Table writes go through the MCP schema tools on Cloud / licensed self-hosted (listTools category tables, then callTool) and through the REST API (curl on Meta API v3) on Community Edition or as a fallback. See mcp-patterns for the contract and api-reference for the REST surface.
Discover First
Before creating or changing a table, snapshot the base:
mcp__plugin_nocodb-dev_nocodb__getBaseInfo ← confirm working base
mcp__plugin_nocodb-dev_nocodb__getBaseSchema ← every table with its fields and views, one call
mcp__plugin_nocodb-dev_nocodb__getTablesList ← or just titles & IDs
Avoid name collisions and unintended duplicates. NocoDB does not enforce title uniqueness within a base — duplicates are accepted but cause downstream confusion.
Create a Table
MCP (Cloud / licensed)
mcp__plugin_nocodb-dev_nocodb__listTools category: "tables" ← once per session: confirms createTable is offered
mcp__plugin_nocodb-dev_nocodb__callTool name: "createTable"
arguments: { title: "Customers", description: "Master customer list",
fields: [ { title: "Name", type: "SingleLineText" },
{ title: "Email", type: "Email" } ] }
REST
curl -sS -X POST \
-H "xc-token: ${NOCODB_TOKEN}" \
-H "Content-Type: application/json" \
-d '{ "title": "Customers" }' \
"${NOCODB_URL}/api/v3/meta/bases/${BASE_ID}/tables"
With initial fields (preferred — saves a roundtrip per field; type-specific settings go inside options):
curl -sS -X POST \
-H "xc-token: ${NOCODB_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"title": "Customers",
"description": "Master customer list",
"fields": [
{ "title": "Name", "type": "SingleLineText" },
{ "title": "Email", "type": "Email" },
{ "title": "Phone", "type": "PhoneNumber" },
{ "title": "Status", "type": "SingleSelect",
"options": { "choices": [
{ "title": "New" }, { "title": "Active" }, { "title": "Archived" }
]}},
{ "title": "Joined", "type": "Date" }
]
}' \
"${NOCODB_URL}/api/v3/meta/bases/${BASE_ID}/tables"
The response includes the new tableId (prefix m). For a source other than the default, add source_id.
Verify
mcp__plugin_nocodb-dev_nocodb__getTableSchema tableId: <newTableId>
The response should list every field you created, with auto-assigned field IDs and the first non-system field as the display field.
Rename a Table
curl -sS -X PATCH \
-H "xc-token: ${NOCODB_TOKEN}" \
-H "Content-Type: application/json" \
-d '{"title":"NewName"}' \
"${NOCODB_URL}/api/v3/meta/bases/${BASE_ID}/tables/${TABLE_ID}"
MCP: callTool name: "updateTable" arguments: { tableId: "<tableId>", title: "NewName" }.
Renaming a table does not rename references in formulas, lookups, or rollups — but those references use IDs internally so they keep working. Visible names in formulas stay as the original; refresh formulas explicitly if you want them to reflect the new name.
Update Description
curl -sS -X PATCH \
-H "xc-token: ${NOCODB_TOKEN}" \
-H "Content-Type: application/json" \
-d '{"description":"New description"}' \
"${NOCODB_URL}/api/v3/meta/bases/${BASE_ID}/tables/${TABLE_ID}"
Set the Display Field
The display field is what shows up in linked-record dropdowns and lookup card titles. By default, NocoDB picks the first non-system column — usually a SingleLineText named "Title" or similar. Override:
curl -sS -X PATCH \
-H "xc-token: ${NOCODB_TOKEN}" \
-H "Content-Type: application/json" \
-d '{"display_field_id":"<fieldId>"}' \
"${NOCODB_URL}/api/v3/meta/bases/${BASE_ID}/tables/${TABLE_ID}"
MCP: callTool name: "setDisplayField" arguments: { fieldId: "<fieldId>" } (category fields), or updateTable with display_field_id.
Allowed display field types: text, number, date/time, duration, autonumber and formula fields. LongText, select, link and attachment fields are rejected.
Duplicate a Table
There is no single duplicate call in the REST API (on Cloud / licensed the MCP duplicates category may offer one — check listTools). To clone by hand:
- Read the source schema:
mcp__plugin_nocodb-dev_nocodb__getTableSchema tableId: <sourceTableId>
- Strip IDs from the response and POST as a new table:
curl -sS -X POST \
-H "xc-token: ${NOCODB_TOKEN}" \
-H "Content-Type: application/json" \
-d @duplicated-table.json \
"${NOCODB_URL}/api/v3/meta/bases/${BASE_ID}/tables"
Note: this clones the schema only. To copy data, see the import-export skill in nocodb-ops.
Delete a Table
Destructive — confirm with the user first. Print the table title, base, record count, and any dependent fields (Lookups / Rollups / Links from other tables) before asking for approval.
curl -sS -X DELETE \
-H "xc-token: ${NOCODB_TOKEN}" \
"${NOCODB_URL}/api/v3/meta/bases/${BASE_ID}/tables/${TABLE_ID}"
MCP: callTool name: "deleteTable" arguments: { tableId: "<tableId>" }.
On Cloud / licensed the deleted table goes to the base trash: listTrash (read-only, lists cleanup_due_at) and restoreFromTrash(trashId) bring it back until the retention window ends. An external source deletes for good.
Pre-delete audit:
mcp__plugin_nocodb-dev_nocodb__countRecords tableId: <tableId>
Then read getBaseSchema and look in every other table's fields for options.related_table_id == <tableId> — those are the relations that will break.
Pre-Flight Checklist for New Tables
Before creating:
- Title. Distinct from existing tables. Use TitleCase or sentence-case consistently within a base.
- Display field. Plan to have a
SingleLineTextearly in the field list — it auto-becomes the display field. - Required fields. NocoDB doesn't enforce required at schema level (validation is per-view in Forms); decide if you need form-level required or webhook-driven validation later.
- Relations. If this table will hold link fields, create the parent tables first.
- Naming convention. Use kebab-case or camelCase for field titles? Pick one. NocoDB stores titles verbatim; the API matches by exact title (case-sensitive).
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
422 on create with fields |
One field's payload doesn't match its type | Check field-types.md for the exact options keys |
| 400 "title required" | Empty title or whitespace-only | Title is mandatory |
| Display field not what you expected | NocoDB picked the first non-system column | Set display_field_id explicitly |
| Delete returns 200 but table still visible | Schema cache | Force-refresh in NocoDB UI or wait ~30s |
| Cannot delete table | A link field on another table points to it | Delete the link field on the other side first |
createTable is not offered by listTools |
Community Edition | Use the REST recipes above |