ChatGPT and local MCP clients

Local connection

An installed client on the same machine uses http://127.0.0.1:38182/mcp/<project-token>, with the project's authentication settings. Tailscale is not required. The project owner verified the locally installed Qwen Studio application; this does not establish compatibility with Qwen Studio's web version or every other client.

On another machine, localhost means that other machine. Configure a reachable MCPBox address and listener, or use an appropriate proxy.

Cloud-hosted ChatGPT

For a direct remote connection, provide a public HTTPS project endpoint. Tailscale Funnel is our recommended option for a local MCPBox installation; an existing HTTPS reverse proxy also works. Keep the admin listener private.

On the MCPBox host, after enabling Funnel prerequisites in Tailscale:

tailscale funnel 38182

Append /mcp/<project-token> to the printed HTTPS URL. Do not append :38182 to that public URL. Keep MCPBox and the foreground Funnel command running. tailscale funnel status checks publication; tailscale funnel 38182 off stops it. Funnel is public; it does not supply MCPBox authentication. See Tailscale's command reference.

Configure the public origin

After obtaining the public HTTPS address, set MCPBOX_PUBLIC_MCP_URL=https://mcp.example.com in the MCPBox service environment, replacing the example with your actual origin, and restart MCPBox. For systemd, add Environment="MCPBOX_PUBLIC_MCP_URL=https://mcp.example.com" in the service override. Do not include /mcp/<project-token> in this variable.

Forward /mcp/, /oauth/, and /.well-known/ to the MCP listener, preserving the paths. If your proxy or tunnel uses path-specific rules, check that it does not strip these prefixes. OAuth routes belong to port 38182, not the admin port 38181.

Check that https://mcp.example.com/.well-known/oauth-authorization-server returns metadata with the public HTTPS origin. A protected MCP request without credentials should advertise a public, project-specific resource_metadata URL in WWW-Authenticate. The project URL displayed and copied in the UI should also use this origin, regardless of the admin panel address. See configuration.

Project OAuth setup

1. Enable bearer authentication for the MCPBox project and verify HTTPS reachability.
2. Start the remote MCP app/connection setup in ChatGPT. Availability and screen names depend on the account/workspace.
3. Copy the exact redirect URL supplied by that setup. In MCPBox, create a named OAuth client for the project with this URL.
4. Where predefined client credentials are requested, use the MCPBox connection name as client ID and its revealed token as client secret. Keep the same setup flow open.
5. Complete authorization and tool discovery, then test a harmless read-only call and check MCPBox Logs.

MCPBox uses preconfigured clients with authorization-code/PKCE, not dynamic registration. Panel OIDC is separate. For the host-side protocol, see official OpenAI authentication documentation.

Troubleshooting

• Wrong public address or OAuth discovery returns 404: check MCPBOX_PUBLIC_MCP_URL in the running service and forward /.well-known/ and /oauth/ to the MCP port, preserving paths. The separate admin port does not serve these routes.
• redirect_uri_mismatch: recreate the named client using the callback from the current setup; restarting setup may change it.
• Authentication succeeds but discovery fails: check the actual running binary, endpoint, tool schemas and proxy routes. OAuth success alone does not verify tool discovery.
• Skills missing: download a package and bind its installed version to that exact project. Refresh the client's cached tools. list_skills need not run on every user message.
• Files: a local attachment/path does not automatically reach MCPBox. Skills execution requires actual bytes uploaded to a server job; see Skills.

The owner verified ChatGPT authentication and Skills instruction discovery/reading. That verification did not include executing third-party Skill scripts.