#NocoBase MCP

After enabling the NocoBase MCP service plugin, the NocoBase application exposes an MCP service endpoint for MCP clients to access and call NocoBase APIs.

#Service URL

• Main application:

  http(s)://<host>:<port>/api/mcp

• Sub-application:

  http(s)://<host>:<port>/api/__app/<app_name>/mcp

This endpoint uses the streamable HTTP transport protocol.

#Capabilities

#General Tools

Can be used to operate data tables.

#NocoBase Core and Plugin APIs

You can control which package APIs are exposed by MCP using the x-mcp-packages request header, for example:

x-mcp-packages: @nocobase/server,plugin-workflow*,plugin-users

This header supports full package names. Names without a scope will be automatically prefixed with @nocobase/.

By default, no package APIs other than general tools are loaded. It is recommended to use NocoBase CLI for operating other system features.

Common packages:

For more packages and related API documentation, refer to the API Documentation plugin.

#Authentication

#API Key Authentication

Call the MCP service endpoint using an API key created through the API keys plugin. Permissions are determined by the role bound to the API key.

#OAuth Authentication

Call the MCP service endpoint using an access token obtained through OAuth authentication. Permissions are determined by the authorized user. If the user has multiple roles, you can set the calling role via the x-role request header.

#Quick Start

#Codex

#Using API Key Authentication

First enable the API Keys plugin and create an API Key.

export NOCOBASE_API_TOKEN=<your_api_key>
codex mcp add nocobase --url https://<host>:<port>/api/mcp --bearer-token-env-var NOCOBASE_API_TOKEN

#Using OAuth Authentication

First enable the IdP: OAuth plugin.

codex mcp add nocobase --url https://<host>:<port>/api/mcp
codex mcp login nocobase --scopes mcp,offline_access

#Claude Code

#Using API Key Authentication

First enable the API Keys plugin and create an API Key.

claude mcp add --transport http nocobase https://<host>:<port>/api/mcp --header "Authorization: Bearer <your_api_key>"

#Using OAuth Authentication

First enable the IdP: OAuth plugin.

claude mcp add --transport http nocobase https://<host>:<port>/api/mcp

After execution, open Claude and select the corresponding MCP service to log in:

claude
/mcp

#OpenCode

#Using API Key Authentication

First enable the API Keys plugin and create an API Key. Configure opencode.json:

{
  "mcp": {
    "nocobase": {
      "type": "remote",
      "url": "https://<host>:<port>/api/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer <your_api_key>"
      }
    }
  },
  "$schema": "https://opencode.ai/config.json"
}

#Using OAuth Authentication

First enable the IdP: OAuth plugin. Configure opencode.json:

{
  "mcp": {
    "nocobase": {
      "type": "remote",
      "url": "https://<host>:<port>/api/mcp",
      "enabled": true
    }
  },
  "$schema": "https://opencode.ai/config.json"
}

Login authentication

opencode mcp auth nocobase

Debug

opencode mcp debug nocobase