User CLI reference

Desktop clients: multiple services in one connection

Use standard OAuth sign-in and explicitly select each service, tool, prompt, resource and subscription. Write requests are off by default and still require individual approval when enabled. Current group permissions and each service grant constrain calls; new tools never expand existing grants. Revoke one service or the whole connection in the portal.

mcpbridge login --native --server https://hub.example.com/mcp --profile work
mcpbridge connect --profile work

Use this flow with a local browser. Administrators preregister native MCP client callbacks under Operations → OAuth clients. Clients use PKCE and standard Bearer credentials without a custom grant header. Headless Agents retain device link authorization, with one service per pairing; existing single-service entries remain available.

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.

This page lists end-user commands. Replace example domains, services, tools, scopes, and ci_example with your actual values. Use --help to see the parameters supported by your installed version.

setup · Connection wizard

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

Optionally set --callback-port. Choose the service, tools, resources, duration, name, and format in the terminal; log in and confirm in the browser. stdout contains a configuration without credentials, while prompts go to stderr.

mcpbridge login --server https://hub.example.com/mcp --client-id mcpbridge --profile work
mcpbridge login --profile work
mcpbridge status --profile work
mcpbridge logout --profile work

login supports repeated --scope arguments and --callback-port. status shows cached login information and checks authorization when a Broker session exists. It does not print tokens.

client add · Manual entry

mcpbridge client add --profile work --name project-a-read --endpoint database-prod --scope mcp:database --scope db:read --tool query --resource /project=project-a --ttl 1h

Parameter	Meaning
--endpoint / --name	Service ID and entry name.
--scope / --tool	Permissions and original tool names. Repeat as needed.
--resource /pointer=value	Resource conditions on tool arguments. Repeat as needed.
--ttl	For example, 30m or 1h, within the server limit, configurable from 1 minute to 8 hours.
--allow-write-requests	Allows write requests; each write still requires approval.

Entries are read-only by default. Omitting tools freezes the currently eligible tool set. Omitting scopes selects the required scopes from your existing permissions. The output uses mcpbridge as command; desktop clients may need its actual absolute path.

Additional capabilities

Add --prompts, --resources, or --subscriptions when needed. Subscriptions also require resources to be allowed. Resource conditions on tool arguments do not restrict resource URIs or prompts. Create separate entries suited to those capabilities.

client list / authorize / revoke

mcpbridge client list --profile work
mcpbridge client authorize --profile work --client ci_example
mcpbridge client authorize --profile work --client ci_example --tool query --resource /project=project-b
mcpbridge client revoke --profile work --client ci_example

Reauthorization preserves unspecified settings; supplied lists replace the old lists. Confirm in the browser and reconnect.

doctor · Diagnostics

mcpbridge doctor --profile work
mcpbridge doctor --profile work --client ci_example
mcpbridge doctor --profile work --client ci_example --json --timeout 30s

The default timeout is 15 seconds; the allowed range is 1 second to 2 minutes. Success or warnings only return exit code 0; blocking problems return 1. No tools are executed. See Troubleshooting.

connect / broker

mcpbridge connect --profile work --client ci_example
mcpbridge broker status
mcpbridge broker stop
mcpbridge broker run

The client launches connect, whose stdout is reserved for MCP. Running it directly in a terminal may wait for input. broker run is for foreground diagnostics. Stopping the Broker does not revoke remote authorizations. Broker logs are stored in broker.log in the private directory.

Compatible connections

Use connect --profile work alone only for services where your administrator explicitly allows connections without client authorization. Enforced authorization requires --client. See Version requirements.