How Chat2DB Handles Authentication and Authorization: Token-Based Security Explained

Chat2DB secures its desktop and CLI APIs using a lightweight UUID token system that validates requests via a custom HTTP header or environment variable rather than a full Spring Security framework.

Chat2DB is an open-source database management tool that implements a simple but effective token-based security model across its community edition server. The Chat2DB authentication and authorization mechanism generates a unique token at startup and enforces it through client-specific interceptors and filters. This design keeps the security surface small while protecting desktop and CLI entry points.

Token Generation and Storage

When the application starts, the system checks for an existing MCP token and creates one if it is absent. The SystemSettingsUtil.getOrCreateMcpAuthToken() method generates a UUID without dashes and persists it under the key MCP_AUTH_TOKEN in system settings.

// chat2db-community-server/chat2db-community-tools/src/main/java/ai/chat2db/community/tools/util/SystemSettingsUtil.java
String authToken = SystemSettingsUtil.getOrCreateMcpAuthToken();

The same utility class retrieves the stored token later for request validation.

Desktop Client Authentication via X-Chat2DB-MCP-Token

All HTTP requests originating from the desktop client must carry the custom header X-Chat2DB-MCP-Token. The header constant is defined in McpSecurityConstants.java at the path chat2db-community-server/chat2db-community-web/src/main/java/ai/chat2db/community/web/api/config/mcp/security/McpSecurityConstants.java.

McpAuthInterceptor and Header Validation

The McpAuthInterceptor intercepts incoming desktop requests, extracts the X-Chat2DB-MCP-Token header, and compares it against the value stored by SystemSettingsUtil. If the header is missing or the value does not match, the request is rejected with the error code common.mcpUnauthorized.

// chat2db-community-server/chat2db-community-web/src/main/java/ai/chat2db/community/web/api/config/mcp/interceptor/McpAuthInterceptor.java
public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
    String headerToken = request.getHeader("X-Chat2DB-MCP-Token");
    String storedToken = SystemSettingsUtil.getOrCreateMcpAuthToken();
    
    if (headerToken == null || !headerToken.equals(storedToken)) {
        throw new BusinessException("common.mcpUnauthorized");
    }
    return true;
}

CLI Runtime Authentication via Environment Variables

The CLI client authenticates through a bearer token supplied via the environment variable chat2db.cli.runtime.token or the Java system property chat2db.cli.runtime.token. This token is validated by CliRuntimeHttpFilter on incoming API calls meant for the CLI.

CliRuntimeHttpFilter and Bearer Token Checks

CliRuntimeHttpFilter checks for the presence and validity of the CLI runtime token. Missing tokens trigger the error code cli_runtime_token_missing, while invalid tokens return cli_runtime_unauthorized.

// chat2db-community-server/chat2db-community-web/src/main/java/ai/chat2db/community/web/api/config/cli/security/CliRuntimeHttpFilter.java
public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) {
    String token = System.getenv("chat2db.cli.runtime.token");
    if (token == null) {
        token = System.getProperty("chat2db.cli.runtime.token");
    }
    
    if (token == null) {
        writeError(response, "cli_runtime_token_missing");
        return;
    }
    
    if (!isValid(token)) {
        writeError(response, "cli_runtime_unauthorized");
        return;
    }
    
    chain.doFilter(request, response);
}

Implicit Authorization in Controllers

After successful token authentication, the request proceeds to the controller layer. Chat2DB does not implement fine-grained role-based access control in the source tree. Instead, authorization is implicit: most operations are permitted for any authenticated user because the tool is primarily developer-focused. The controller methods execute the requested operation directly once the token check passes.

This means there are no additional role checks after McpAuthInterceptor or CliRuntimeHttpFilter validate the request.

Summary

• Token generation: SystemSettingsUtil.getOrCreateMcpAuthToken() creates and persists a UUID token under MCP_AUTH_TOKEN at startup.
• Desktop authentication: The X-Chat2DB-MCP-Token header is validated by McpAuthInterceptor against the stored UUID.
• CLI authentication: CliRuntimeHttpFilter checks the chat2db.cli.runtime.token environment variable or system property.
• Error handling: Invalid desktop requests return common.mcpUnauthorized; CLI failures return cli_runtime_token_missing or cli_runtime_unauthorized.
• Authorization: Once authenticated, users can execute operations without additional role checks.

Frequently Asked Questions

Does Chat2DB use Spring Security for authentication?

No. According to the Chat2DB source code, the community edition avoids a full Spring Security framework and instead relies on lightweight custom interceptors and filters. The McpAuthInterceptor and CliRuntimeHttpFilter handle validation independently using UUID tokens.

What happens if the X-Chat2DB-MCP-Token header is missing?

The McpAuthInterceptor rejects the request and returns the error code common.mcpUnauthorized. This interceptor is defined in chat2db-community-server/chat2db-community-web/src/main/java/ai/chat2db/community/web/api/config/mcp/interceptor/McpAuthInterceptor.java.

How is the CLI token different from the desktop token?

The desktop client uses an MCP token passed in the X-Chat2DB-MCP-Token HTTP header, while the CLI client uses a runtime token configured through the chat2db.cli.runtime.token environment variable or system property. Each entry point has its own validation filter: McpAuthInterceptor for desktop and CliRuntimeHttpFilter for CLI.

Is there role-based access control in Chat2DB?

No. The source code shows no fine-grained role checks. Chat2DB authentication and authorization are focused on simple token validation, and once a request is authenticated, controllers implicitly authorize the operation without further permission checks.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}