# MCP Server
> Part of the NocoDB documentation (APIs & MCP). Index of all pages: https://nocodb.com/llms.txt. Any docs page is available as Markdown by adding `.md` to its URL.
URL: https://nocodb.com/docs/apis-and-mcp/mcp
Last updated: 2026-10-03
Connect NocoDB to Large Language Models (LLMs) through the NocoDB Model Context Protocol (MCP) server.
The **Model Context Protocol (MCP) Server** lets you connect NocoDB to LLMs that support MCP, for example Claude, Cursor, Windsurf, or Codex. The LLM then works directly with your NocoDB base:
* On all editions, it can query and edit records.
* On NocoDB Cloud and licensed self-hosted deployments, it can also manage tables, fields, views, workflows, interfaces, permissions, and more.
## Available tools
All editions give the record tools. With the record tools, an MCP client can:
* list tables and read their schema
* query, count, and aggregate records
* read attachments
* create, update, and delete records
* add or remove single links through a link field
The record tools take a maximum of 100 records in each call.
| Action | Purpose | Sample Prompt |
| ------ | ------------------------------ | ------------------------------------------------------------- |
| Create | Add new records | Create a task named 'Review Documentation' |
| Read | Look up information | Show me all projects with deadlines this week |
| Update | Change existing data | Mark the status of Project X as completed & re-assign to John |
| Delete | Remove records | Remove all tasks assigned to John |
| Link | Link or unlink related records | Link the onboarding tasks to the Acme project |
Updating a link field through the update tool replaces the whole set, so pass the complete list of linked records you want, or
`[]`
to clear it.
`null`
is not a link value and leaves the links untouched. The link and unlink tools add or remove individual links without restating the set.
On NocoDB Cloud and licensed self-hosted deployments, the server also gives tools for the rest of the workspace. Each tool uses the same service as the matching REST API. Thus validation, permissions, and audit work the same way.
| Area | What an MCP client can do |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Records | Link records by their display value, not by record id. Upsert records that match on a maximum of three business-key fields, not on record id. Set the same field values on all records that match a condition, in one call and with no 100-record limit. |
| Tables and fields | Create, update, and delete tables and fields. Add or remove select options. Set the display field of a table. Read the base schema in one call: all tables you can see, with their fields and views. |
| Views, filters, and sorts | Create and configure views. Replace their filters. Manage sorts. |
| Scripts | List, read, create, update, and delete scripts. |
| Dashboards | Manage dashboards and widgets. Read widget data. |
| Webhooks and comments | Manage webhooks. List, post, resolve, and delete comments. |
| Interfaces | Create and configure interface pages. Publish an interface to make its draft pages live. |
| Workflows | Read and write workflow drafts. Add nodes and test nodes. Publish an automation after all its nodes are tested. |
| Permissions | Set table permissions, field permissions, and Record-Level Security policies. |
| Audits | Read the change history of one record. Base owners can also read the audit log of a full base, filtered by user, event type, or date range. |
| Documents | Create and edit pages. Patch Markdown. Manage share links. |
| Attachments | Upload files into an Attachment field from an http(s) or `data:` URL, with a maximum of 10 files in each call. The tool adds the files to the cell that you name, or returns them for you to write into a record. |
| Trash | List the items in the base trash. Restore one entry by its trash id. Restore deleted records by row id. Only tables on a NocoDB-managed source keep deleted rows. |
| Record templates | List, read, create, update, and delete record templates. Create a record from a template, together with the records that the template links. |
| Data import and export | Export a table or view to CSV or as an `.xlsx` workbook. Import CSV into a table. Exported Decimal and Currency values keep their stored precision, not the display setting of the field. |
| Duplicates | Duplicate tables, fields, views, and bases. Poll the job status. |
| Links | Get the web app URL for a table, view, workflow, interface, dashboard, script, or document. |
| Row coloring | Manage record color conditions and rules. |
| Date dependencies | Read, set, and remove the rule that links a start field, an end field, and a link field. With this rule, when you move one record, the records that depend on it move too. |
| Folders and shared views | Manage base, view, and workflow folders. List shared views. |
| Members and teams | For a base: list the members and the teams that have a role on the base, and give, change, or remove the role of a person or a team. For a workspace: list the members and teams, invite people, change a workspace role, and remove a person. |
| Bases and workspaces | List workspaces and bases. Create and read bases. Rename a base or change its icon color. |
A test of a workflow node over MCP is a check, not a run. The node does not do its action. For example, a create-record node writes no row, and a messaging node sends nothing. NocoDB resolves the node configuration against the results of the nodes before it and checks it with read-only calls. The result shows as simulated.
Some nodes can only be checked with a real run, for example a script step or a node that declares no outputs. For these nodes, the test fails and MCP cannot clear the failure. You cannot publish until someone runs that step in the automation editor.
Linking by display value matches exactly and adds to the existing links. A value that matches no record, or that matches more than one, is reported back instead of being linked, so link by record id where titles repeat. Updating by condition requires a condition: there is no form of it that updates every record.
Conditions on a form field and on a Record-Level Security policy are written as one flat list. If those conditions are already grouped, the tool that replaces them refuses the call and leaves them as they are, so edit them in the form view or in the policy itself. View filters and record colour conditions do accept nested groups.
A connection can never grant a role above the one you hold, and it cannot remove you from a workspace. The workspace member and team tools need a connection that reaches the workspace, so they are not offered on one created from a base's
**MCP Server**
screen. Renaming a base and changing its icon colour are the only base settings a connection can write.
Tools respect the token owner's base role: viewers can read, editors can write records, views, filters, and sorts, and creators can change schema. Tools for plan-gated features appear only when the workspace plan includes the feature, and Record-Level Security policies apply to MCP requests.
In the Community Edition, the MCP server exposes the record tools only.
## Connection tools and access
On all editions except the Community Edition, you create an MCP connection for your account, not for a single base. When you create it, you select what it can do. Use one connection for one MCP client.
**Access** sets what the connection can reach. Add the bases that it can use, or give it all resources.
**Tools & Permissions** is an allowlist of the tools that the connection can call. NocoDB does not register a tool that you do not allow, so the tool does not show in the tool list of the client. Set each section to **Read**, **Read & write**, **Read, write & delete**, or **None**. To allow single tools instead, expand the section.
| Section | What it covers | A new connection starts at |
| ----------------------------- | ----------------------------------------------------------------------- | -------------------------- |
| Records & data | Records, comments, import and export | Read, write & delete |
| Schema | Tables, fields, duplicating, and how a base is organized | Read, write & delete |
| Views | Views, filters, sorts, sharing, form fields, row colors | Read, write & delete |
| Automation | Workflows, webhooks, scripts, and agents | Read, write & delete |
| Interfaces, dashboards & docs | Interface pages, dashboards, widgets, and documents | Read, write & delete |
| Account & workspaces | Who you are, your workspaces, the bases in them, and links into the app | Read |
| Access & security | Field and table permissions, row-level security | Read |
| Platform | Integrations, environments, and apps | Read |
You can change a connection after you create it:
1. Open the connection from the list, or click **Edit connection** in its row menu.
2. Rename the connection, or change its **Access** and **Tools & Permissions**.
The change applies on the next call of the client, and the key stays the same. NocoDB shows the key only when you create or regenerate a connection.
A connection can never do more than you can. Its authority is the part of your selection that your own roles also permit. NocoDB resolves this authority on each tool call, so a role change applies from the next call. Two rules are outside the access list:
* A connection can always reach a base that it creates.
* MCP connections cannot create a workspace.
Connections created before scopes existed keep working and carry your own access to the one base they were created for. To bound one, delete it and create a new connection.
## API call usage
A tool call counts toward the **API Calls** allowance of the workspace. It counts as the same work would cost over the REST API, not as one call for each request. If a client sends several tool calls in one request, NocoDB charges each of them.
| Tool | Counts as |
| ------------------------------ | ------------------------------------------------------------------------- |
| Link records, unlink records | one call per record, since the REST route takes one record at a time |
| Create, update, delete records | one call per 10 records, the REST bulk limit |
| Export CSV | one call per 1,000 rows returned |
| Upload attachments, import CSV | one call, since the REST route takes the whole set or file in one request |
| Every other tool | one call |
## Desktop LLM Clients
Each MCP endpoint in NocoDB gives a secure URL. You can link this URL to an MCP-compatible client.
After you configure it, the LLM can do database operations in your workspace from natural language prompts. You do not write SQL or scripts.
### Server Configuration (NocoDB)
1. Open **Account Settings** and select the **MCP** tab.
2. Click **New connection**.
3. Type a name for the connection.
4. Below [**Access**](#connection-tools-and-access), add the bases that it can reach, or give access to all resources.
5. Below **Tools & Permissions**, allow the tools that this connection can call.
6. Click **Create connection**. NocoDB generates the MCP Config JSON.
7. Copy the generated JSON configuration. You use it in the configuration of your LLM client.
The **MCP Server** screen of a base lists the connections that reach that base. New connections that you create there are pinned to that base. Thus this screen does not show **Access** when you create or edit a connection. To change the access of a connection, use the **MCP** tab in **Account Settings**.
In the Community Edition, you create connections for each base:
1. In the left sidebar, click **Overview**.
2. Select the **Settings** tab.
3. Select **Model Context Protocol**.
4. Click **New MCP Endpoint**. This creates a new MCP config JSON for your base.
5. Type a name for the MCP endpoint.
6. Click **Create**. NocoDB generates the MCP Config JSON.
7. Copy the generated JSON configuration. You use it in the configuration of your LLM client.
### Client Configuration
#### Claude
1. Open **Claude Desktop Preferences** (`⌘+,`).
2. Under **Develop**, click **Edit Config**.
3. Insert the JSON block that you copied [here](#server-configuration-nocodb) as `claude_desktop_config.json`.
4. Save the file.
5. Restart Claude Desktop.
#### Cursor
1. Open **Cursor Settings** (`⇧+⌘+J`).
2. Open the **MCP** tab.
3. Select **Add Custom MCP**.
4. Paste the JSON block that you copied [here](#server-configuration-nocodb).
5. Save.
On success, you will see the number of tools enabled below the MCP Server just installed. If you see an error, double-check the JSON configuration.
#### Windsurf
1. Open **Windsurf Settings** (`⌘+,`).
2. In the **Cascade** section > `Plugins (MCP Server)`, click **Manage Plugins**.
3. Paste the JSON block that you copied [here](#server-configuration-nocodb).
4. Save.
#### AntiGravity
1. In the top right of the agent window, click the three dots.
2. Select **MCP Servers**.
3. Click **Manage MCP Servers**.
4. Click **View raw config**. A file opens.
5. Paste the JSON block that you copied [here](#server-configuration-nocodb) into the file.
6. Save.
#### Codex
Codex CLI connects directly to the MCP endpoint over HTTP. Thus it does not need the `mcp-remote` bridge. It uses a TOML configuration, not the shared JSON block.
1. Open `~/.codex/config.toml`. If the file does not exist, create it.
2. Add the TOML block from the **Codex** tab of the MCP endpoint dialog. Use the URL and token that you generated [here](#server-configuration-nocodb).
3. Run `codex mcp list`. Make sure that the server is connected.
```toml
[mcp_servers.NocoDB_MCP]
url = "https://your-domain.com/mcp/"
http_headers = { "x-api-key" = "" }
```
The table key has to be a bare TOML key, so NocoDB replaces any character outside letters, digits,
`_`
, and
`-`
in the endpoint name: an endpoint named
`My Base MCP`
appears as
`[mcp_servers.My_Base_MCP]`
.
### JSON Example
```json
{
"mcpServers": {
"NocoDB MCP": {
"command": "npx",
"args": [
"mcp-remote",
"https://your-domain.com/mcp/",
"--header",
"x-api-key: "
]
}
}
}
```
The MCP endpoint also accepts the token in an
`xc-mcp-token`
header, so existing configurations using it keep working.
Your MCP configurations generated above functions as a set of access credentials, granting full control over your NocoDB base. Ensure it remains confidential, never include it in source control, and store it only in secure, protected locations.
## Web based LLM Clients (OAuth)
Connect NocoDB to web-based LLM applications with OAuth. The LLM then gets database access directly from the browser, and you do not set up a desktop client. This method gives granular permission controls, and you do not configure JSON manually.
The authorization screen has the same **Access** and **Tools & Permissions** pickers as an MCP connection. Thus a client reaches only the bases that you add and calls only the tools that you allow. The screen starts at **Read & write** for **Records & data** and at **Read** for all other sections.
Some clients name the permissions that they need in the authorization request. They use `:` pairs, for example `records:read` or `tables:write`. The level is `read`, `write` or `delete`. For these clients:
* The screen shows the requested permissions below **Requested permissions**, in place of the **Tools & Permissions** picker.
* You cannot edit this list. Authorize it as it is, or cancel.
* You still select the bases that the client reaches, below **Access**.
* The screen marks a permission that NocoDB does not offer. If you authorize, the client gets an `invalid_scope` error, not a grant.
Authorizations granted before these pickers existed keep working and stay limited to the single base they named. To change what a client reaches, disconnect it and authorize again.
### Claude Web
With the OAuth integration, Claude web users can access NocoDB databases through the connectors interface.
#### Setup Steps
1. Click [here](https://claude.ai/settings/connectors). Claude Web Settings opens in a new tab.
* Alternatively, in the Claude Web app, go to **Settings** > **Connectors**.
2. Click **Add custom connector**.
3. In the "Add custom connector" dialog, do these steps:
* Type a name for the connector.
* Enter the MCP endpoint URL: `https://app.nocodb.com/mcp`
* Click `Add`.
4. The list shows the NocoDB Connector in the "Disconnected" state. Click **Connect**. The OAuth authorization flow starts in a new tab.
5. Authorize access:
* If you are not logged in, log in to your NocoDB account.
* Below [**Access**](#connection-tools-and-access), add the bases that Claude can reach, or give it all resources.
* Below **Tools & Permissions**, allow the tools that Claude can call.
* Confirm the permissions that Claude gets:
* Access the resources you selected on your behalf
* Use only the tools you allowed
* Act with your own permissions in those resources
* Click **Authorize** to give access.
**Authorize** stays disabled until you add a minimum of one resource and allow a minimum of one tool. If Claude names its own permissions, the screen has no tool picker, and you only add a resource.
This capture predates the
**Access**
and
**Tools & Permissions**
pickers, which are offered on NocoDB Cloud and licensed self-hosted deployments. Without a licence the screen stays as shown here: a single base selector above the permission summary.
The NocoDB connector then changes to the "Connected" state in Claude Web. You can now work with your NocoDB data in the Claude web application.
Self-hosted users should replace
[https://app.nocodb.com](https://app.nocodb.com)
with their NocoDB instance URL
#### Configure Tool Permissions
By default, all tools are set to "Always ask permission". Thus you control each operation that Claude does. You can change these settings.
1. Click [here](https://claude.ai/settings/connectors). Claude Web Settings opens in a new tab.
2. On the NocoDB connector, click **Configure**.
3. In the dropdown menu of each tool, set its permission level:
| Permission level | Result |
| ------------------------- | ---------------------------------------------------------- |
| **Always ask permission** | Claude must get your approval each time it uses this tool. |
| **Allow unsupervised** | Claude can use this tool without your approval. |
To get the Workspace and Base information that this connector can access, use the "Get Base Info" tool.
#### Using NocoDB Tools in Claude Web
After you configure the connector, you can work with your NocoDB data through conversation. For example:
* "Show me all projects with deadlines this week"
* "Create a task named 'Review Documentation'"
* "Mark the status of Project X as completed and reassign to John"
* "Provide details of our top 3 sponsors"
Claude does these requests with the enabled NocoDB tools. It reads from and writes to your database within the permissions that you gave.
OAuth authorization functions as a set of access credentials granting Claude control over the NocoDB resources you selected. Only authorize access to bases and tools you trust Claude to use on your behalf.
### ChatGPT
With the OAuth integration, OpenAI web users (ChatGPT) can connect securely to NocoDB databases through the MCP connector, directly from the browser. This method gives the same granular access control. You do not configure it manually or set up a desktop client.
#### Prerequisites
To add custom connectors, enable Developer Mode in the ChatGPT settings.
1. Open [ChatGPT Settings](https://chatgpt.com/#settings/Connectors) in a new tab.
* Alternatively, click your **Profile Icon** → **Settings** → **Settings** → **Apps & Connectors**).
2. Click **Advanced Settings**.
3. Enable **Developer Mode**.
#### Setup Steps
1. Open [ChatGPT Settings](https://chatgpt.com/#settings/Connectors) in a new tab.
* Alternatively, click your **Profile Icon** → **Settings** → **Settings** → **Apps & Connectors**).
2. In the top right corner of the **Connectors** modal, click **Create**.
3. In the "New connector" dialog, do these steps:
* Type a name for the connector. You can also add a description or an icon.
* Enter the MCP Server URL: `https://app.nocodb.com/mcp`
* Select the **I trust this application** check box.
* Click `Create`.
4. Authorize access:
* If NocoDB asks you to log in, log in to your NocoDB account.
* Below [**Access**](#connection-tools-and-access), add the bases that ChatGPT can reach, or give it all resources.
* Below **Tools & Permissions**, allow the tools that ChatGPT can call.
* Review and confirm the requested permissions:
* Access to the resources you selected on your behalf
* Use of only the tools you allowed
* Acting with your own permissions in those resources
* Click **Authorize**.
When the authorization is complete, ChatGPT Web shows a confirmation message. The message tells you that the NocoDB connector is connected.
For self-hosted users, replace
`https://app.nocodb.com`
with your NocoDB instance URL.
#### Using NocoDB Tools in OpenAI Web
In the ChatGPT interface, start a new conversation. Then do these steps:
1. Click the **+** icon. The "Tools" menu opens.
2. If `Developer Mode` is not enabled, enable it.
3. Click `More`.
4. Find and select the NocoDB connector that you created.
5. Click the toggle to enable the connector.
After you configure the connector, you can query or update your NocoDB data through conversation. For example:
* “List all open support tickets assigned to me”
* “Add a new contact named ‘Alice Chen’ to the CRM base”
* “Update the status of Order #2456 to ‘Shipped’”
* “Summarize total revenue by month from the Sales base”
ChatGPT does these actions with the connected NocoDB tools, within the permissions that you gave.
OAuth authorization provides ChatGPT controlled access to the NocoDB resources you selected. Only authorize the bases and tools you trust ChatGPT to manage on your behalf.
---
## Related pages
- [APIs & MCP](https://nocodb.com/docs/apis-and-mcp.md): Programmatic access to NocoDB: REST APIs for data and metadata, and an MCP server for connecting your bases to LLMs.
- [Skills](https://nocodb.com/docs/apis-and-mcp/skills.md): Use the NocoDB skill for Claude to manage NocoDB bases through natural language.