MCP Patterns

NocoDB MCP Tools Reference

All tools use the mcp__nocodb__ prefix. Every tool call goes through the NocoDB MCP server.

Discovery Tools

Use these first to understand what data is available.

Always start with getTablesList to get table IDs. You need a tableId for almost every other tool.

Read Tools

Retrieve data without changing anything.

Write Tools

Create, change, or remove data.

Analytics Tools

Run calculations across your data.

File Tools

Work with file attachments stored in records.

Filter Syntax

Filters use the format: (field,operator,value)

Operators:

Combine filters with ~and, ~or, ~not:

(Status,eq,Active)~and(Priority,eq,High)

Common Patterns

Pattern 1 -- List with filter and sort

Find all active orders sorted by date, showing only key fields:

Tool: mcp__nocodb__queryRecords
Params:
  tableId: <orders_table_id>
  where: "(Status,eq,Active)"
  fields: ["Order Number", "Customer", "Total", "Date"]
  sort: ["-Date"]
  pageSize: 25

Prefix a field name with - to sort descending.

Pattern 2 -- Create and verify

Add a new record, then confirm it was saved:

Step 1 - Tool: mcp__nocodb__createRecords
Params:
  tableId: <contacts_table_id>
  records: [{ "fields": { "Name": "Jane Smith", "Email": "jane@example.com" } }]

Step 2 - Tool: mcp__nocodb__queryRecords
Params:
  tableId: <contacts_table_id>
  where: "(Email,eq,jane@example.com)"

Pattern 3 -- Aggregate report

Get total revenue and order count, split by status:

Tool: mcp__nocodb__aggregate
Params:
  tableId: <orders_table_id>
  aggregations: [
    { "field": "Total", "type": "sum" },
    { "field": "Id", "type": "count" }
  ]
  filterGroups: [
    { "alias": "Active", "where": "(Status,eq,Active)" },
    { "alias": "Completed", "where": "(Status,eq,Completed)" }
  ]

Best Practices

1. Resolve table IDs first -- always call getTablesList before operating on data. Never guess IDs.
2. Check the schema -- call getTableSchema to confirm exact field names and types before querying.
3. Use pagination -- set pageSize (default is 25, max is 2000) and use page for large datasets.
4. Filter on the server -- apply where filters instead of fetching all records and filtering locally.
5. Request only needed fields -- use fields[] to limit returned data and keep responses fast.
6. Bulk operations -- prefer batch calls (up to 2000 records) over looping one-by-one.

Error Handling