MCP Server

The Model Context Protocol (MCP) Server lets you connect NocoDB with LLMs that support MCP, such as Claude, Cursor, Windsurf, or Codex. With this integration, LLMs can work directly with your NocoDB base: query and edit records and, on NocoDB Cloud and licensed self-hosted deployments, manage tables, fields, views, workflows, interfaces, permissions, and more.

Available tools

Every edition exposes 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, and add or remove individual links through a link field. Record tools take up to 100 records per call.

On NocoDB Cloud and licensed self-hosted deployments, the server also exposes tools for the rest of the workspace. Each tool wraps the same service as the matching REST API, so validation, permissions, and audit behave identically.

Testing a workflow node over MCP is a check, not a run. The node does not carry out its action, so a create-record node writes no row and a messaging node sends nothing. Its configuration is resolved against the results of the nodes upstream of it and checked with read-only calls, and the result comes back marked as simulated. A node that can only be checked by running it for real, such as a script step or a node that declares no outputs, comes back as a failed test that MCP cannot clear, and publishing stays blocked until someone runs that step in the automation editor.

Connection tools and access

Outside the Community Edition, an MCP connection is created against your account rather than a single base, and you choose what it is allowed to do when you create it. One connection is meant for one MCP client.

Access is where the connection reaches: add the bases it may use, or grant it all resources.

Tools & Permissions is an allowlist of the tools the connection may call. A tool you do not allow is never registered, so it does not appear in the client's tool list at all. Each section is set to Read, Read & write, Read, write & delete, or None; expand one to allow individual tools instead.

A connection can be changed after it is created. Open it from the list, or use Edit connection in its row menu, to rename it or change its Access and Tools & Permissions; the change applies on the client's next call and the key stays the same. The key itself is shown only when a connection is created or regenerated.

A connection can never do more than you can. Its authority is what you picked, intersected with your own roles, and it is resolved on every tool call, so a role change applies from the next call onwards. Two things sit outside the access list: a base the connection creates is always reachable by it, and creating a workspace is not offered to MCP connections at all.

API call usage

A tool call counts towards the workspace's API Calls allowance for what the same work would cost over the REST API, rather than as one call per request. A client that sends several tool calls in a single request is charged for each of them.

Desktop LLM Clients

Each MCP endpoint in NocoDB provides a secure URL that can be linked to an MCP-compatible client. Once configured, the LLM can execute database operations in your workspace through natural language prompts, without writing SQL or scripts.

Server Configuration (NocoDB)

1. Open Account Settings and select the MCP tab.
2. Click New connection.
3. Provide a name for the connection.
4. Under Access, add the bases it may reach, or grant access to all resources.
5. Under Tools & Permissions, allow the tools this connection may call.
6. Click Create connection to generate the MCP Config JSON.
7. Copy the generated JSON configuration. This will be used in your LLM client configuration.

A base's MCP Server screen lists the connections that reach that base and creates new ones pinned to it, so Access is not shown there, whether you are creating a connection or editing one. Change a connection's access from the MCP tab in Account Settings.

In the Community Edition, connections are created per base instead:

1. Click on the Overview button in the left sidebar.
2. Select the Settings tab.
3. Select the Model Context Protocol
4. Click on the New MCP Endpoint to create a new MCP config JSON for your base.
5. Provide a name for the MCP endpoint
6. Click Create to generate the MCP Config JSON.
7. Copy the generated JSON configuration. This will be used in your LLM client configuration.

Client Configuration

Claude

1. Open Claude Desktop Preferences (⌘+,).
2. Under Develop, click Edit Config.
3. Insert the JSON block copied here as claude_desktop_config.json.
4. Save the file and restart Claude Desktop.

Cursor

1. Go to Cursor Settings (⇧+⌘+J).
2. Open the MCP tab and select Add Custom MCP.
3. Paste the JSON block copied here. Save.

Windsurf

1. Open Windsurf Settings (⌘+,).
2. In the Cascade section > Plugins (MCP Server) > Click Manage Plugins
3. Paste the JSON block copied here. Save.

AntiGravity

1. Click the three dots in the top right of the agent window and select MCP Servers.
2. Click Manage MCP Servers.
3. Click View raw config.
4. Paste the JSON block copied here into the file that opens. Save.

Codex

Codex CLI connects to the MCP endpoint over HTTP directly, so it needs no mcp-remote bridge and takes a TOML configuration instead of the shared JSON block.

1. Open ~/.codex/config.toml, creating it if it does not exist.
2. Add the TOML block shown in the Codex tab of the MCP endpoint dialog, using the URL and token generated here.
3. Run codex mcp list to confirm 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 using OAuth, enabling seamless database access directly from the browser without requiring desktop client setup. This approach grants granular permission controls and eliminates the need for manual JSON configuration.

The authorization screen carries the same Access and Tools & Permissions pickers as an MCP connection, so a client reaches only the bases you add and calls only the tools you allow. It starts at Read & write on Records & data and at Read everywhere else.

Some clients name the permissions they need in the authorization request itself, as <category>:<level> pairs such as records:read or tables:write, where the level is read, write or delete. When a client does, the screen lists what it asked for under Requested permissions in place of the Tools & Permissions picker, and the list cannot be edited: authorize it as it stands or cancel. Which bases the client reaches is still yours to choose under Access. A permission NocoDB does not offer is listed as such, and authorizing sends the client back an invalid_scope error instead of a grant.

Claude Web

OAuth-based integration allows Claude web users to access NocoDB databases through the connectors interface.

Setup Steps

1. Click here to open Claude Web Settings in a new tab.

   • Alternatively, navigate to Settings > Connectors from the Claude Web app.

2. Click Add custom connector.

3. In the "Add custom connector" dialog:

   • Provide a connector name of your choice
   • Enter the MCP endpoint URL: https://app.nocodb.com/mcp
   • Click Add

4. NocoDB Connector will now be listed in "Disconnected" state. Click Connect to initiate the OAuth authorization flow (Opens in a new tab).

5. Authorize Access

   • You will be asked to log in to your NocoDB account (if not already logged in)
   • Under Access, add the bases Claude may reach, or grant it all resources
   • Under Tools & Permissions, allow the tools Claude may call
   • Confirm the permissions Claude will have
     • 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 grant access

   Authorize stays disabled until you have added at least one resource and allowed at least one tool. Where Claude names its own permissions, there is no tool picker and a resource is all that is needed.

With this, the NocoDB connector will move to "Connected" state in Claude Web. You can now interact with your NocoDB data through Claude web application.

Configure Tool Permissions

By default, all tools are set to "Always ask permission" to ensure you have control over each operation Claude performs. You can modify these settings as needed.

Click here to open Claude Web Settings in a new tab. Click Configure on the NocoDB connector to manage tool permissions. Set each tool's permission level using the dropdown menu:

• Always ask permission — Your approval is required every time Claude uses this tool
• Allow unsupervised — Claude can use this tool without requesting approval

To retrieve Workspace & Base information that this connector has access to, use the "Get Base Info" tool.

Using NocoDB Tools in Claude Web

Once configured, you can interact with your NocoDB data conversationally. 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 will execute these requests using the enabled NocoDB tools, reading from and writing to your database based on the permissions you've granted.

ChatGPT

OAuth-based integration enables OpenAI web users (ChatGPT) to securely connect with NocoDB databases through the MCP connector, directly from their browser environment. This provides the same granular access control and eliminates the need for manual configuration or desktop client setup.

Prerequisites

Enable Developer Mode in ChatGPT settings to allow custom connector additions.

1. Open ChatGPT Settings in a new tab.
   • Alternatively, click your Profile Icon → Settings → Settings → Apps & Connectors).
2. Click Advanced Settings & enable Developer Mode.

Setup Steps

1. Open ChatGPT Settings in a new tab.
   • Alternatively, click your Profile Icon → Settings → Settings → Apps & Connectors).
2. Click Create button in top right corner of the Connectors modal.
3. In the "New connector" dialog:
   • Provide a connector name of your choice. Optionally, add a description / icon.
   • Enter the MCP Server URL: https://app.nocodb.com/mcp
   • Check the box for I trust this application.
   • Click Create
4. Authorize Access:
   • Log in to your NocoDB account if prompted
   • Under Access, add the bases ChatGPT may reach, or grant it all resources
   • Under Tools & Permissions, allow the tools ChatGPT may call
   • Review and confirm the permissions being requested:
     • 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

Once authorization completes, you will see a confirmation message in ChatGPT Web indicating the NocoDB connector is now connected.

Using NocoDB Tools in OpenAI Web

On the ChatGPT interface, start a new conversation and

• Click the + icon to open the "Tools" menu, enable Developer Mode if not already enabled.
• Click More to find and select the NocoDB connector you created. Toggle to enable it.

Once configured, you can query or update your NocoDB data conversationally. 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 executes these actions using the connected NocoDB tools according to the permissions granted.