Goal

Workflow

1. Confirm which app endpoint should be used:
   • Main app:

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

   • Non-main app:

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

2. Verify NocoBase is running and accessible.
3. Determine the auth mode:
   • API Key: require the

     API Keys

     plugin and an existing API key
   • OAuth: require the

     IdP: OAuth

     plugin
4. Guide the user to add the NocoBase MCP server using the command for their CLI.
5. Verify the MCP connection by checking the registered server and available tools.

Service Notes

• NocoBase MCP uses the

  streamable HTTP

  transport protocol.
• NocoBase exposes:
  • NocoBase core and plugin APIs
  • A generic CRUD tool for operating on collections

MCP Configuration

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

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

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

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

claude
/mcp

Prerequisites

• NocoBase is installed and running
• The correct app endpoint is known
• For API Key auth:

  • API Keys

    plugin is enabled
  • an API key has been created
• For OAuth auth:

  • IdP: OAuth

    plugin is enabled

Verification

codex mcp list
codex mcp get nocobase

claude
/mcp