Command line

The same mcp-reference-server command, with a subcommand. It talks to a running server over MCP.

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.