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 project:

• 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.

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.

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.

Outside the Community Edition, the server also exposes Generate Skill Guide (generateSkillGuide). It returns Markdown files covering the tools this connection can actually reach, area by area, along with the workspaces and projects it can see, for a client that keeps skills on disk to write under .claude/skills/nocodb-mcp. The bundle includes a SKILL.md entry point, so the folder works as a skill once the files are written. Ask for it once at the start of a session. Passing sections: ["scope"] returns only the reachable workspaces and projects, which is the part that changes most often. It sits outside the tool allowlist described below, so it is always offered, and it reports only what the connection itself can reach.

On NocoDB Cloud and licensed self-hosted deployments, the server also gives Submit Feedback (submitFeedback). With this tool, an MCP client reports a NocoDB bug, a missing capability, a confusing behavior, or a docs gap to the NocoDB team. The report changes nothing in your workspace, and the call answers with a feedback id. You cannot read a report back.

NocoDB also tells the client to report a problem that it meets during a task, and to tell you what it reported. A report carries the client's own description of the problem, not your records.

Submit Feedback sits outside the tool allowlist described below, so every connection has it. It is available only where the deployment can deliver reports: NocoDB Cloud, and self-hosted deployments whose license carries feedback credentials.

Connection tools and access

On all editions except the Community Edition, you create an MCP connection for your account, not for a single project. 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 projects 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. A new connection starts every section at Read, write & delete, so narrow the ones that a client does not need.

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 project that it creates.
• MCP connections cannot create a workspace.

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.

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, add the projects 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 project lists the connections that reach that project. New connections that you create there are pinned to that project. 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 project:

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 project.
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 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.
5. Save.

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.
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 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.
3. Run codex mcp list. Make sure that the server is connected.

[mcp_servers.NocoDB_MCP]
url = "https://your-domain.com/mcp/<ncId>"
http_headers = { "x-api-key" = "<ncToken>" }

JSON Example

{
  "mcpServers": {
    "NocoDB MCP": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-domain.com/mcp/<ncId>",
        "--header",
        "x-api-key: <ncToken>"
      ]
    }
  }
}

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 projects that you add and calls only the tools that you allow. The screen starts every section at Read, write & delete.

Some clients name the permissions that they need in the authorization request. They use <category>:<level> 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 projects 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.

Claude Web

With the OAuth integration, Claude web users can access NocoDB databases through the connectors interface.

Setup Steps

1. Click here. 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, add the projects 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.

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.

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. 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:

To get the Workspace and Project information that this connector can access, use the "Get Project 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.

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 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 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, add the projects 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.

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 project”
• “Update the status of Order #2456 to ‘Shipped’”
• “Summarize total revenue by month from the Sales project”

ChatGPT does these actions with the connected NocoDB tools, within the permissions that you gave.