#NocoBase MCP

Após habilitar o plugin de serviço MCP do NocoBase, o aplicativo NocoBase passa a expor uma interface de serviço MCP para que clientes MCP possam acessar e invocar as APIs do NocoBase.

#Endereço do serviço

• Aplicação principal:

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

• Sub-aplicação:

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

Esse endereço utiliza o protocolo de transporte streamable HTTP.

#Capacidades oferecidas

#Ferramentas gerais

Podem ser usadas para operar tabelas de dados.

#APIs do core do NocoBase e dos plugins

Você pode controlar quais pacotes têm suas APIs expostas pelo MCP através do header x-mcp-packages, por exemplo:

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

Esse header aceita o nome completo do pacote; quando não há scope, ele é completado automaticamente para @nocobase/.

Por padrão, nenhum pacote é carregado além das ferramentas gerais. É mais recomendado utilizar a abordagem do NocoBase CLI para operar outras funcionalidades do sistema.

Pacotes comuns:

Mais pacotes e descrições de APIs relacionadas podem ser conhecidas através do plugin API documentation.

#Métodos de autenticação

#Autenticação via API Key

Use uma API key criada pelo plugin API keys para chamar a interface do serviço MCP. As permissões são determinadas pelo papel associado à API key.

#Autenticação via OAuth

Use o access token obtido após a autorização OAuth para chamar a interface do serviço MCP. As permissões são determinadas pelo usuário autorizado. Caso o usuário tenha múltiplos papéis, é possível definir o papel ativo na chamada através do header x-role.

#Início rápido

#Codex

#Usando autenticação via API Key

Habilite primeiro o plugin API Keys e crie uma API Key.

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

#Usando autenticação via OAuth

Habilite primeiro o plugin IdP: OAuth.

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

#Claude Code

#Usando autenticação via API Key

Habilite primeiro o plugin API Keys e crie uma API Key.

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

#Usando autenticação via OAuth

Habilite primeiro o plugin IdP: OAuth.

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

Após executar, abra o Claude e faça login no serviço MCP correspondente:

claude
/mcp

#OpenCode

#Usando autenticação via API Key

Habilite primeiro o plugin API Keys e crie uma API Key. Configure o opencode.json:

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

#Usando autenticação via OAuth

Habilite primeiro o plugin IdP: OAuth. Configure o opencode.json:

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

Autenticar login:

opencode mcp auth nocobase

Debug:

opencode mcp debug nocobase