For remote or headless Agents, use link authorization: sign in and choose access on one page, or use --interactive-auth for authentication tools. The existing setup flow below remains available.

1 Get details2 Install3 Run setup4 Configure client5 Check

1. Get connection details from your administrator

What you needExample or explanation
Full MCPHub URLhttps://hub.example.com/mcp, including the path.
CLI client IDFor example, mcpbridge. This identifies the registered sign-in application, not the ci_… client-entry ID generated later.
AccessYour company account is enabled and has permission to use the target service and tools.
Callback portRequired only when your administrator specifies a fixed port, such as 8765.

2. Install the local connector

Download mcpbridge for your operating system and CPU, verify its checksum, and extract it. See Install the connector. Your AI client must be able to run the executable; setup uses its actual absolute path.

3. Run setup on the computer that runs your AI client

mcpbridge setup --server https://hub.example.com/mcp --client-id mcpbridge --profile work > mcphub-mcp.json

work is a local connection profile name that you can choose. If the profile already has sign-in details, use mcpbridge setup --profile work > mcphub-mcp.json. Add --callback-port 8765 when a fixed port is required.

  1. Sign in with your company identity in the browser.
  2. Return to the terminal. Choose one service from the wizard's list, then choose specific tool numbers. Service and tool selection happens in the terminal.
  3. Choose resource limits, grant duration, and a client name as needed. Start with the read-only tools you need. Write and unclassified tools require additional confirmation.
  4. Choose an output format: convert generic JSON to TOML for Codex; use generic JSON for clients such as Claude Code; choose the dedicated servers JSON format for VS Code.
  5. Open the authorization page shown by the terminal. Compare the pairing code in both places, check the service, tools, and data limits, and confirm authorization.
Listed tools are not yet authorized for useYou must confirm the request in the browser. Selecting no tools does not grant all tools. Each client entry connects to one service; run setup separately for additional services.

4. Add the generated configuration to your AI client

Open mcphub-mcp.json and preserve the actual command, args, and env.MCPHUB_HOME when present. Merge the entry into your existing client configuration, then reload the MCP connection. Setup does not edit or overwrite the AI client's own configuration file.

Follow the steps for Codex, Claude Code, or VS Code.

5. Confirm that the connection works

Your client should show the authorized tools. Check the actual client ID from the generated configuration:

mcpbridge doctor --profile work --client ci_example

Setup and diagnostics check the connection, authorization, and catalog without executing tools. If a personal account is required, connect it in your portal and retry. If the final diagnostic fails after authorization, configuration may still have been generated. Keep it and follow the diagnostic advice.

What to do next

Start with a clear read-only task, such as asking your agent to find project information you may access. See Use tools and data. Before changing data, read Approve a write operation.

Run setup and your AI client on the same computer under the same operating-system account. SSH, containers, and remote development cannot directly reuse local paths and broker connections. See Multiple services and environments.