With no arguments the command is the MCP server, which is what the editor pages on this site run. With a command such as status it is a client for a server that is already running, here or hosted. It needs Node 18 or later.
Look at a server
A local desk (npm run http in server/) is the default target, http://127.0.0.1:8787/mcp.
npx mcp-reference-server --help
npx mcp-reference-server status
npx mcp-reference-server tools
npx mcp-reference-server call run_query schema=tickets 'filter={"status":"open"}' limit=5
Groups
Negotiates io.modelcontextprotocol/groups. tools/list then returns only describe_server and get_schema. groups tickets fetches the query group and lists open tickets. It does not create a ticket. Those calls show up on /log, and in the call trace once audit is on. Turn the extension off with update_settings groups=false (admin). That leaves each tool's own gate alone. The same sequence is on Help → Tools and the Try button on /tools.
npx mcp-reference-server groups npx mcp-reference-server groups get query npx mcp-reference-server groups tickets
Point it at a hosted server
Give the base address or the /mcp address. MCP_URL does the same. A pasted /admin or /health address also works.
npx mcp-reference-server status --url https://your-app.onrender.com
export MCP_URL=https://your-app.onrender.com/mcp
npx mcp-reference-server call run_query schema=tickets 'filter={"id":"TCK-1001"}'
Sign in for the operate tools
Rate limit, users, keys, settings and the log need the admin scope, even while auth mode is off. A key wins over a user. demo / demo is the built-in admin on a laptop. Prefer --password-stdin or MCP_PASSWORD to --password, which stays in your shell history.
export MCP_API_KEY=mcpk_xxxxxxxx_your_admin_key npx mcp-reference-server users list echo demo | npx mcp-reference-server users list --user demo --password-stdin
Configure
npx mcp-reference-server auth-mode write npx mcp-reference-server rate-limit --limit 30 --window 60 npx mcp-reference-server trace on npx mcp-reference-server users create alice --scopes read,write npx mcp-reference-server keys create --label ci --scopes read npx mcp-reference-server settings export --out settings.json
Commands that delete, revoke, import or turn a transport off ask first. Without a terminal they refuse; add --yes for scripts. A key secret is printed once, when it is created.
The demo setup
The same state and checks as Admin → Remote config → Demo setup. Four users, four keys, call trace on, sample traffic, auth mode write, 30 calls per 60 seconds. Use it on a server you own: it changes real settings.
npx mcp-reference-server demo apply --user demo --password demo --keys-file demo-keys.json npx mcp-reference-server demo check --user demo --password demo --keys-file demo-keys.json npx mcp-reference-server demo remove --user demo --password demo
In scripts
--json prints one JSON document on stdout, errors included. Exit codes: 0 done, 1 the server refused or a check failed, 2 usage error, 3 server not reachable.
KEY=$(npx mcp-reference-server keys create --label ci --scopes read --json | jq -r .key) npx mcp-reference-server demo check --json --user demo --password-stdin <<< demo || echo "not set up"
All commands
status · tools · groups · call · settings · auth-mode · rate-limit · trace · gate · lock · scope · mqtt · protocols · ui-auth · users · keys · demo. Run mcp-reference-server help <command> for the options of one.
The same operations have forms on the Browser page and in Admin → Remote.