NocoDB MCP — Discovery and Schema Writes
All tools use the mcp__plugin_nocodb-dev_nocodb__ prefix (the server is declared in this plugin's .mcp.json).
The Contract: Community vs Cloud / Licensed
| Edition |
What the MCP server offers |
Schema writes go through |
| Community Edition |
Record tools and read tools only |
REST (curl on Meta API v3) — see api-reference |
| Cloud / licensed self-hosted |
The same listed tools, plus schema, view, hook, workflow, dashboard, script, permission, RLS, interface and docs write tools that stay out of the tool list |
MCP first: listTools(category) → callTool(name, arguments); REST is the fallback |
Rule of thumb for every skill in this plugin: on Cloud/licensed, prefer the MCP write tools; on Community Edition — or when listTools is missing or a tool is not in its answer — use REST.
Detect the edition once per session
mcp__plugin_nocodb-dev_nocodb__listTools category: "tables"
- The answer contains
createTable / updateTable / deleteTable → Cloud/licensed. Use MCP-first.
listTools is absent, errors, or the tables category is empty → Community Edition. Use REST.
whoami shows which user and which base the MCP credential is pinned to; effective authority is the intersection of that grant and the user's role on each resource — a 403 on a write usually means the role is not an editor/creator, not a missing tool.
Two Kinds of Tools
Listed directly (read tools and record CRUD — always visible):
| Group |
Tools |
| Orientation |
whoami, getBaseInfo, getBaseSchema (every table with fields, options and views in one call), getTablesList, getTableSchema |
| Schema reads |
listFields, getField, getFieldOptionsSchema(type), listViews, getView, listFilters, listSorts, listHooks, getHook, listWorkflows, getWorkflow, listDashboards, listScripts, listBaseMembers |
| Records |
queryRecords, getRecord, countRecords, createRecords, updateRecords, deleteRecords, aggregate, groupByRecords, linkRecords, unlinkRecords, listLinkedRecords |
Behind listTools(category) (Cloud/licensed): call listTools with one category, read the names and argument schemas it returns, then invoke the tool through callTool. Categories:
workspaces, members, links, tables, fields, filters, sorts, views, shared-views, data-io, record-templates, date-dependencies, duplicates, audits, dashboards, comments, records, attachments, trash, permissions, row-colors, scripts, hooks, view-sections, base-sections, automation-sections, workflows, workflow-nodes, rls, interfaces, docs, form-fields.
The ones this plugin uses most:
| Category |
Tools |
Skill |
tables |
createTable, updateTable, deleteTable |
table-management |
fields |
createField, updateField, deleteField, addFieldOptions, removeFieldOptions, setDisplayField |
field-management |
views |
createView, updateView, deleteView |
view-management |
filters |
createFilter, updateFilter, replaceFilters, deleteFilter |
view-management |
sorts |
addSort, updateSort, deleteSort |
view-management |
shared-views |
shareView, unshareView |
view-management |
hooks |
createHook, updateHook, deleteHook |
webhooks |
workflows / workflow-nodes |
createWorkflow, updateWorkflow, publishWorkflow, deleteWorkflow, node and edge tools, validateWorkflowNode |
workflows |
trash |
listTrash, restoreFromTrash, restoreRecords |
table-management |
audits |
listBaseAudits, listRecordAudits |
troubleshoot |
docs |
createDocument, updateDocument, patchDocument, moveDocument, deleteDocument, shareDocument |
api-reference |
Calling a hidden tool
mcp__plugin_nocodb-dev_nocodb__listTools category: "fields"
→ names + argument schemas — read them, do not guess key names
mcp__plugin_nocodb-dev_nocodb__callTool name: "createField"
arguments: { tableId: "<tableId>",
field: { title: "Phone", type: "PhoneNumber" } }
callTool validates arguments against the same schema listTools returned. If a hidden tool name is not in the answer for its category, the instance does not offer it — fall back to REST.
MCP Payloads vs REST Payloads
The two surfaces share the v3 key names, but the MCP tools wrap or split them differently:
| Topic |
MCP |
REST (Meta API v3) |
| Create a field |
createField {tableId, field:{title, type, options}} |
POST /tables/{tableId}/fields body {title, type, options} |
| Update a field |
updateField {fieldId, field:{…}} — options keys merge onto the stored ones; changing type replaces them |
PATCH /fields/{fieldId} |
| Select choices |
addFieldOptions / removeFieldOptions (choices:[{title,color?}]) |
POST / DELETE /fields/{fieldId}/options |
Field options shape |
getFieldOptionsSchema(type) returns the exact JSON Schema; unknown keys are rejected |
FieldOptions_* schemas in nocodb-meta-openapi.json |
| Create a view |
createView {tableId, title, type, lock_type?, options?, fields?} — filters and sorts are separate tools |
POST /tables/{tableId}/views also accepts filters, sorts, row_coloring |
| Filters |
createFilter {viewId, filter}, groups use group_operator: "AND"|"OR" |
POST /views/{viewId}/filters |
| Update a hook |
updateHook is a full replacement — read with getHook and resend every key |
PATCH /hooks/{hookId} |
| Barcode format key |
options.format (per getFieldOptionsSchema("Barcode")) |
options.barcode_format |
Links type |
not in the MCP enum — use LinkToAnotherRecord |
both Links and LinkToAnotherRecord |
When the two disagree, the MCP tool's own schema wins for MCP calls and the bundled OpenAPI spec wins for REST calls.
Record tools write at most 100 records per call — chunk bulk loads (see nocodb-ops).
The Discovery → Change → Verify Loop
1. getBaseSchema (or getTablesList + getTableSchema) ← one-call orientation / snapshot
2. plan the change (table / field / view / hook payload)
3. confirm destructive steps with the user
4. apply: callTool(createField …) on Cloud/licensed
curl … /api/v3/meta/… on Community, or as fallback
5. getTableSchema(tableId) ← confirm the new shape landed
6. queryRecords / getRecord (optional) ← confirm data is still readable
Pattern — Add a Field (MCP-first)
Step 1: mcp__plugin_nocodb-dev_nocodb__getTablesList
→ find the table, note its ID
Step 2: mcp__plugin_nocodb-dev_nocodb__getTableSchema tableId: <tableId>
→ confirm the title is free; for Lookup/Rollup confirm the link field exists
Step 3: mcp__plugin_nocodb-dev_nocodb__callTool name: "createField"
arguments: { tableId: "<tableId>", field: { title: "Phone", type: "PhoneNumber" } }
(Community Edition: POST /api/v3/meta/bases/{baseId}/tables/{tableId}/fields)
Step 4: mcp__plugin_nocodb-dev_nocodb__getTableSchema tableId: <tableId>
→ the new field appears in `fields`
Pattern — Verify a Formula After Creation
A Formula is computed server-side; the only proof is reading records.
Step 1: createField via callTool, or the REST recipe in field-management
field: { title: "Days Open", type: "Formula",
options: { formula: "DATETIME_DIFF(NOW(), {CreatedAt}, \"days\")" } }
Step 2: mcp__plugin_nocodb-dev_nocodb__queryRecords
tableId: <tableId>
fields: ["Title", "CreatedAt", "Days Open"]
pageSize: 5
→ spot-check that Days Open holds plausible numbers
Pattern — Audit Scope Before a Destructive Change
Step 1: mcp__plugin_nocodb-dev_nocodb__countRecords tableId: <tableId>
Step 2: mcp__plugin_nocodb-dev_nocodb__countRecords tableId: <tableId>
filter: { field: "Status", operator: "blank" }
→ rows that hold no value in the column you are about to change
Deleted tables, fields and views go to the base trash on Cloud/licensed: listTrash shows the entry (with cleanup_due_at), restoreFromTrash(trashId) puts it back. Deleted records can be restored with restoreRecords only on a NocoDB-managed source — an external source deletes for good. Still confirm before every delete.
Best Practices
- Resolve IDs first. Never pass a guessed
tableId/fieldId; read getBaseSchema or getTablesList first.
- Snapshot before and after. A diff of two
getTableSchema answers is your audit trail.
- Read the argument schema.
listTools(category) and getFieldOptionsSchema(type) tell you the exact keys; the servers reject unknown ones.
- Check the edition before choosing the path. MCP-first only where
listTools offers the tool; otherwise REST.
- Verify with reads. A successful write response does not always mean the schema cache has caught up — re-read with
getTableSchema.
- Watch for view-filter blindness.
queryRecords with a viewId returns only rows visible through that view's filters. Omit viewId for raw audits.
Error Handling
| Error |
Meaning |
What to do |
| "Table not found" |
Wrong tableId |
Re-run getTablesList |
| "Field not found" |
Stale schema cache or wrong name (names are case-sensitive) |
Re-run getTableSchema |
| Unknown key rejected on a field/view payload |
options key not in that type's schema |
getFieldOptionsSchema(type) / listTools for the exact keys |
listTools or callTool not found, or tool missing from the category |
Community Edition, or an older server |
Use the REST recipes in api-reference |
| 401 / 403 from MCP |
Token invalid, or the role cannot write schema |
See setup → MCP rows; check whoami |
1---2name: mcp-patterns-93description: |4 NocoDB MCP for schema-development work — what the server lists directly, which schema tools hide behind listTools/callTool, and the Community vs Cloud/licensed contract. Use when:5 - "what MCP tools can I use for schema?"6 - "can MCP create tables / fields / views?"7 - "listTools / callTool"8 - "how do I discover NocoDB structure?"9 - "MCP for nocodb-dev"10metadata:11 source: https://skillmd.com/skills/agents-store/mcp-patterns-912---1314# NocoDB MCP — Discovery and Schema Writes1516All tools use the `mcp__plugin_nocodb-dev_nocodb__` prefix (the server is declared in this plugin's `.mcp.json`).1718## The Contract: Community vs Cloud / Licensed1920| Edition | What the MCP server offers | Schema writes go through |21|---------|----------------------------|--------------------------|22| **Community Edition** | Record tools and read tools only | **REST** (`curl` on Meta API v3) — see **api-reference** |23| **Cloud / licensed self-hosted** | The same listed tools, plus schema, view, hook, workflow, dashboard, script, permission, RLS, interface and docs **write** tools that stay out of the tool list | **MCP first**: `listTools(category)` → `callTool(name, arguments)`; REST is the fallback |2425Rule of thumb for every skill in this plugin: **on Cloud/licensed, prefer the MCP write tools; on Community Edition — or when `listTools` is missing or a tool is not in its answer — use REST.**2627### Detect the edition once per session2829```30mcp__plugin_nocodb-dev_nocodb__listTools category: "tables"31```3233- The answer contains `createTable` / `updateTable` / `deleteTable` → Cloud/licensed. Use MCP-first.34- `listTools` is absent, errors, or the `tables` category is empty → Community Edition. Use REST.3536`whoami` shows which user and which base the MCP credential is pinned to; effective authority is the intersection of that grant and the user's role on each resource — a 403 on a write usually means the role is not an editor/creator, not a missing tool.3738## Two Kinds of Tools3940**Listed directly** (read tools and record CRUD — always visible):4142| Group | Tools |43|-------|-------|44| Orientation | `whoami`, `getBaseInfo`, `getBaseSchema` (every table with fields, options and views in **one** call), `getTablesList`, `getTableSchema` |45| Schema reads | `listFields`, `getField`, `getFieldOptionsSchema(type)`, `listViews`, `getView`, `listFilters`, `listSorts`, `listHooks`, `getHook`, `listWorkflows`, `getWorkflow`, `listDashboards`, `listScripts`, `listBaseMembers` |46| Records | `queryRecords`, `getRecord`, `countRecords`, `createRecords`, `updateRecords`, `deleteRecords`, `aggregate`, `groupByRecords`, `linkRecords`, `unlinkRecords`, `listLinkedRecords` |4748**Behind `listTools(category)`** (Cloud/licensed): call `listTools` with one category, read the names and argument schemas it returns, then invoke the tool through `callTool`. Categories:4950`workspaces`, `members`, `links`, `tables`, `fields`, `filters`, `sorts`, `views`, `shared-views`, `data-io`, `record-templates`, `date-dependencies`, `duplicates`, `audits`, `dashboards`, `comments`, `records`, `attachments`, `trash`, `permissions`, `row-colors`, `scripts`, `hooks`, `view-sections`, `base-sections`, `automation-sections`, `workflows`, `workflow-nodes`, `rls`, `interfaces`, `docs`, `form-fields`.5152The ones this plugin uses most:5354| Category | Tools | Skill |55|----------|-------|-------|56| `tables` | `createTable`, `updateTable`, `deleteTable` | table-management |57| `fields` | `createField`, `updateField`, `deleteField`, `addFieldOptions`, `removeFieldOptions`, `setDisplayField` | field-management |58| `views` | `createView`, `updateView`, `deleteView` | view-management |59| `filters` | `createFilter`, `updateFilter`, `replaceFilters`, `deleteFilter` | view-management |60| `sorts` | `addSort`, `updateSort`, `deleteSort` | view-management |61| `shared-views` | `shareView`, `unshareView` | view-management |62| `hooks` | `createHook`, `updateHook`, `deleteHook` | webhooks |63| `workflows` / `workflow-nodes` | `createWorkflow`, `updateWorkflow`, `publishWorkflow`, `deleteWorkflow`, node and edge tools, `validateWorkflowNode` | workflows |64| `trash` | `listTrash`, `restoreFromTrash`, `restoreRecords` | table-management |65| `audits` | `listBaseAudits`, `listRecordAudits` | troubleshoot |66| `docs` | `createDocument`, `updateDocument`, `patchDocument`, `moveDocument`, `deleteDocument`, `shareDocument` | api-reference |6768### Calling a hidden tool6970```71mcp__plugin_nocodb-dev_nocodb__listTools category: "fields"72 → names + argument schemas — read them, do not guess key names7374mcp__plugin_nocodb-dev_nocodb__callTool name: "createField"75 arguments: { tableId: "<tableId>",76 field: { title: "Phone", type: "PhoneNumber" } }77```7879`callTool` validates `arguments` against the same schema `listTools` returned. If a hidden tool name is not in the answer for its category, the instance does not offer it — fall back to REST.8081## MCP Payloads vs REST Payloads8283The two surfaces share the v3 key names, but the MCP tools wrap or split them differently:8485| Topic | MCP | REST (Meta API v3) |86|-------|-----|--------------------|87| Create a field | `createField {tableId, field:{title, type, options}}` | `POST /tables/{tableId}/fields` body `{title, type, options}` |88| Update a field | `updateField {fieldId, field:{…}}` — `options` keys **merge** onto the stored ones; changing `type` replaces them | `PATCH /fields/{fieldId}` |89| Select choices | `addFieldOptions` / `removeFieldOptions` (`choices:[{title,color?}]`) | `POST` / `DELETE /fields/{fieldId}/options` |90| Field `options` shape | `getFieldOptionsSchema(type)` returns the exact JSON Schema; unknown keys are rejected | `FieldOptions_*` schemas in `nocodb-meta-openapi.json` |91| Create a view | `createView {tableId, title, type, lock_type?, options?, fields?}` — filters and sorts are separate tools | `POST /tables/{tableId}/views` also accepts `filters`, `sorts`, `row_coloring` |92| Filters | `createFilter {viewId, filter}`, groups use `group_operator: "AND"\|"OR"` | `POST /views/{viewId}/filters` |93| Update a hook | `updateHook` is a **full replacement** — read with `getHook` and resend every key | `PATCH /hooks/{hookId}` |94| Barcode format key | `options.format` (per `getFieldOptionsSchema("Barcode")`) | `options.barcode_format` |95| `Links` type | not in the MCP enum — use `LinkToAnotherRecord` | both `Links` and `LinkToAnotherRecord` |9697When the two disagree, the MCP tool's own schema wins for MCP calls and the bundled OpenAPI spec wins for REST calls.9899Record tools write at most **100 records per call** — chunk bulk loads (see **nocodb-ops**).100101## The Discovery → Change → Verify Loop102103```1041. getBaseSchema (or getTablesList + getTableSchema) ← one-call orientation / snapshot1052. plan the change (table / field / view / hook payload)1063. confirm destructive steps with the user1074. apply: callTool(createField …) on Cloud/licensed108 curl … /api/v3/meta/… on Community, or as fallback1095. getTableSchema(tableId) ← confirm the new shape landed1106. queryRecords / getRecord (optional) ← confirm data is still readable111```112113## Pattern — Add a Field (MCP-first)114115```116Step 1: mcp__plugin_nocodb-dev_nocodb__getTablesList117 → find the table, note its ID118119Step 2: mcp__plugin_nocodb-dev_nocodb__getTableSchema tableId: <tableId>120 → confirm the title is free; for Lookup/Rollup confirm the link field exists121122Step 3: mcp__plugin_nocodb-dev_nocodb__callTool name: "createField"123 arguments: { tableId: "<tableId>", field: { title: "Phone", type: "PhoneNumber" } }124 (Community Edition: POST /api/v3/meta/bases/{baseId}/tables/{tableId}/fields)125126Step 4: mcp__plugin_nocodb-dev_nocodb__getTableSchema tableId: <tableId>127 → the new field appears in `fields`128```129130## Pattern — Verify a Formula After Creation131132A Formula is computed server-side; the only proof is reading records.133134```135Step 1: createField via callTool, or the REST recipe in field-management136 field: { title: "Days Open", type: "Formula",137 options: { formula: "DATETIME_DIFF(NOW(), {CreatedAt}, \"days\")" } }138139Step 2: mcp__plugin_nocodb-dev_nocodb__queryRecords140 tableId: <tableId>141 fields: ["Title", "CreatedAt", "Days Open"]142 pageSize: 5143 → spot-check that Days Open holds plausible numbers144```145146## Pattern — Audit Scope Before a Destructive Change147148```149Step 1: mcp__plugin_nocodb-dev_nocodb__countRecords tableId: <tableId>150Step 2: mcp__plugin_nocodb-dev_nocodb__countRecords tableId: <tableId>151 filter: { field: "Status", operator: "blank" }152 → rows that hold no value in the column you are about to change153```154155Deleted tables, fields and views go to the base **trash** on Cloud/licensed: `listTrash` shows the entry (with `cleanup_due_at`), `restoreFromTrash(trashId)` puts it back. Deleted records can be restored with `restoreRecords` only on a NocoDB-managed source — an external source deletes for good. Still confirm before every delete.156157## Best Practices1581591. **Resolve IDs first.** Never pass a guessed `tableId`/`fieldId`; read `getBaseSchema` or `getTablesList` first.1602. **Snapshot before and after.** A diff of two `getTableSchema` answers is your audit trail.1613. **Read the argument schema.** `listTools(category)` and `getFieldOptionsSchema(type)` tell you the exact keys; the servers reject unknown ones.1624. **Check the edition before choosing the path.** MCP-first only where `listTools` offers the tool; otherwise REST.1635. **Verify with reads.** A successful write response does not always mean the schema cache has caught up — re-read with `getTableSchema`.1646. **Watch for view-filter blindness.** `queryRecords` with a `viewId` returns only rows visible through that view's filters. Omit `viewId` for raw audits.165166## Error Handling167168| Error | Meaning | What to do |169|-------|---------|------------|170| "Table not found" | Wrong `tableId` | Re-run `getTablesList` |171| "Field not found" | Stale schema cache or wrong name (names are case-sensitive) | Re-run `getTableSchema` |172| Unknown key rejected on a field/view payload | `options` key not in that type's schema | `getFieldOptionsSchema(type)` / `listTools` for the exact keys |173| `listTools` or `callTool` not found, or tool missing from the category | Community Edition, or an older server | Use the REST recipes in **api-reference** |174| 401 / 403 from MCP | Token invalid, or the role cannot write schema | See **setup** → MCP rows; check `whoami` |