Projects and client connections

Configure a project

A project combines MCP servers, CLI links, Skills, knowledge collections and a prompt behind one URL. Set its root directory to an existing directory on the machine running MCPBox; CLI commands use this as their working directory.

The project views separate MCP, Skills, CLI, RAG and Prompt settings. Enable only the integrations you want the client to use. Pausing a project blocks requests to its MCP endpoint; disabling a server removes it from aggregation.

Add an MCP server

Transport	Configuration
Local stdio	Executable, arguments, working directory and environment. MCPBox manages the process.
Remote HTTP	The remote MCP URL and its authentication settings. The remote service runs independently.

Use environment fields for secrets rather than embedding credentials in command arguments. Remote server authentication is separate from the Bearer token protecting your project endpoint.

MCPBox checks servers on creation and update and offers a manual Check action. A check performs an MCP handshake and capability discovery; some integrations also receive a diagnostic tool probe. The Info action inspects local stdio server metadata, tools, resources, prompts and a nearby README. Individual tools can be disabled in the server's tool settings.

Connect an AI client

Copy the connection URL from the project interface. A typical local address is:

http://localhost:38182/mcp/<project-token>

Use HTTP MCP transport in a compatible client. For a client on another machine, replace localhost with the reachable server address. Inside a container, localhost points to that container.

If project Bearer protection is enabled, configure:

Authorization: Bearer <project-bearer-token>

The project URL token and Bearer token have different purposes. Administrator session tokens and administrative agent tokens are also separate credentials. After regenerating a project token, update affected clients.

MCPBox combines tools, resources and prompts from enabled servers and routes calls back to the source. Duplicate upstream names receive aliases where needed. Depending on project settings, it also exposes get_project_env_and_rules, search_project_knowledge, CLI tools and the project_prompt MCP prompt.

Project prompt

Use the Prompt view for project instructions and rules. A nonempty prompt is exposed through MCP as project_prompt. A general MCP client chooses whether to request and apply that prompt; connecting the URL alone does not force every model to use it. The llama.cpp launcher also passes it as a system prompt file.

Local launchers

• Ollama: install ollama, make a model available, select it in the project and use the launch action when available.
• LM Studio: choose Launch Project → Add to LM Studio, then confirm the link in LM Studio.
• llama.cpp: install llama-server in PATH, choose a local .gguf model or set MCPBOX_LLAMACPP_MODEL, then use the llama.cpp launch action. MCPBox starts the server and opens its web UI.

These programs and model files are installed separately. Available launch actions depend on detected dependencies and project configuration.

Project OAuth connections

For clients such as ChatGPT that use the provided OAuth flow:

1. Enable project Bearer protection.
2. Create a named OAuth connection in the project and enter the exact callback URL supplied by the client.
3. Use the connection name as the client ID and its generated token as the client secret.
4. Configure the reachable project MCP URL in the client and complete authorization.

This is a preconfigured client flow with authorization code and PKCE (S256), not dynamic client registration. Disable or delete a connection to revoke it. OIDC sign-in to the administration panel is a separate feature.

For remote access, provide an HTTPS endpoint through your deployment's reverse proxy and preserve the MCP, OAuth and discovery routes. See configuration.

Project ordering

Drag the project handle or use the up/down controls and keyboard. Ordering is stored per user in the current browser, new projects append at the end, and it is not synchronized across devices. Current source opens the first project in that saved order after reload. This fix follows v1.4.0; an older binary may select the first ID instead. Refreshing the list preserves an existing manual selection.

A project with connected Skills alone can also accept MCP connections. See Skills for the workflow, and ChatGPT and local clients for cloud versus local connections.

HTTP response formats

For remote HTTP MCP servers, MCPBox sends Accept: application/json, text/event-stream unless a custom Accept header is configured. Successful JSON replies keep the existing JSON decoding path. Responses with Content-Type: text/event-stream are read as SSE: multiline data: fields are combined and the JSON-RPC response with the matching request ID is returned, skipping notifications and unrelated events. Reading stops when that response arrives, without waiting for the server to close the stream.

Legacy JSON responses with missing or incorrect content types remain supported. Recognizable SSE prefixes also allow a mislabelled stream to be read without retrying the request. HTTP failures and JSON-RPC errors remain errors; a failed call is never automatically sent again to try another format. Response size limits and request cancellation still apply. The same reader is used for server health checks and working MCP calls.