Configuration and storage

Network listeners

Environment variable	Default	Purpose
MCPBOX_HOST	127.0.0.1	Administration bind address.
MCPBOX_PORT	38181	Administration port.
MCPBOX_MCP_HOST	127.0.0.1	Project MCP bind address.
MCPBOX_MCP_PORT	38182	Project MCP port.
MCPBOX_PUBLIC_MCP_URL	unset	Public HTTPS origin for MCP/OAuth, without a path.

For example, to keep the previous administration port:

MCPBOX_PORT=38180 ./MCPBox

The executable also accepts -host, -port, -mcp-host and -mcp-port; explicit flags take precedence over environment settings. The MCP listener serves connection, OAuth/discovery and health routes, not the admin UI.

A bind address such as 0.0.0.0 is not a client destination. Use a reachable host name or IP in client settings. For remote HTTPS access, place a reverse proxy in front of the required listener. Preserve MCP, /oauth/* and /.well-known/* routes, the public host/protocol information and streaming behavior. Provide access to the admin listener separately if remote administration or OIDC callbacks are needed.

Public MCP URL and OAuth

Set MCPBOX_PUBLIC_MCP_URL=https://mcp.example.com in the MCPBox process environment and restart the service. Use an HTTPS origin only: no credentials, path, query or fragment. An optional trailing slash is accepted. Invalid values are ignored; without a valid value, MCPBox uses request/proxy-based address detection.

This origin is used for OAuth discovery, protected-resource metadata and the preferred project connection URL (https://mcp.example.com/mcp/<project-token>). The UI displays and copies the URL supplied by the backend, even when the admin panel uses another domain or port. This setting does not change listener bind addresses or configure a proxy.

With separate listeners, /.well-known/ and /oauth/ are served on the MCP listener (38182 by default); the admin listener returns 404 for these routes. Forward these paths and /mcp/ to the MCP listener. OIDC sign-in to the administration panel still uses /api/pro/sso/callback on the admin listener. See ChatGPT connection and network access.

Runtime files

By default these paths are resolved beside the executable:

Path	Contents
mcpbox.db	SQLite application database, including bootstrap and access state.
package_store/	Managed installed packages.
skill_store/	Skills packages, job inputs and outputs.
knowledge_base/	Local collection data and indexes.
.mcpboxpro/rag-shadow/	Compatibility path for RagBox shadow data.

Keep the directory writable and persistent. Starting the same binary from a different current directory does not select a new database. Keep credentials and configured external source paths as part of your deployment configuration.

Storage settings

The storage view separates bootstrap SQLite, the desired operational backend, and the backend reported as active.

• SQLite remains the bootstrap database, including authentication and storage configuration.
• PostgreSQL can hold operational integration state and project/knowledge shadow records. Configure host, port, database, schema, username and password.
• The original project/server records and base audit writes still use the shared SQLite store. Selecting PostgreSQL does not migrate the complete application to PostgreSQL.
• If the configured PostgreSQL connection is unavailable or incomplete, the runtime reports a fallback to SQLite. Check the active backend and fallback reason after saving.

ClickHouse and Elasticsearch settings currently provide configuration and connectivity/status checks for a desired logs backend. The existing audit writers still write through the shared store; a reachable status does not establish complete external log delivery. Do not remove SQLite or its backups after changing these settings.

Logs and diagnostics

Use the project and global logs to review control actions, MCP methods, health traces, access events. The metrics view summarizes request volume, errors, latency and traffic. Health checks mask secrets in diagnostic traces, but keep credentials in environment fields rather than command arguments.

For backup and migration steps, see upgrading. OIDC settings are listed under access; RagBox settings are under integrations.

Settings interface

Settings are grouped into System (Storage, RagBox) and Security (Access, Users, Sessions). The ! button opens help; storage diagnostics are collapsed. Saved configuration is not proof of connectivity. RagBox errors appear in its section with Retry and technical details.

The appearance control at the bottom of navigation and on the sign-in screen selects Light, Dark or System. Its choice is saved in this browser.

Network access

Both ports default to local-only access. For a direct connection from another machine, explicitly set --mcp-host 0.0.0.0 or the required network address, then configure firewall, HTTPS and authentication. Never enter 0.0.0.0 as a client destination. A same-machine proxy, including Funnel, can use local 127.0.0.1:38182. See ChatGPT connections.

Back up the database and skill_store/ as one consistent snapshot. MCPBOX_RUNTIME_CONTEXT_HMAC_SECRET is no longer used: PolicyBox migration.