mcporter CLI conventions

Contract

Emit mcporter's real command surface whenever a task drives the mcporter CLI: the call verb with a dotted server.tool selector, the bare key=value/key:value argument syntax, and the exact subcommand and flag names for inspecting, authenticating, configuring, and code-generating MCP servers. Apply this any time a shell command or instruction targets mcporter.

Rules

1. Call a tool — mcporter call <server>.<tool>. The target is ONE dotted token joining the

server name and the tool name with a single . (mcporter call linear.list_issues). Never split it into two arguments (mcporter call linear list_issues) and never use --server / --tool flags. The call verb may be dropped as shorthand (mcporter linear.list_issues), but the dotted selector is mandatory.

1. Arguments — bare key=value or key:value. Attach tool arguments directly after the

selector as key=value or key:value tokens (team=ENG limit:5), NOT as GNU flags (--team ENG). Other accepted forms:

• Whole JSON object: --args '{"limit":5}' — use for nested or structured parameters.
• Function-call: 'linear.create_issue(title: "Bug")' — positional order follows the schema.
• Value from a file: key=@path — body=@./notes.md reads the file as that argument's value.

1. Inspect servers — mcporter list. Bare mcporter list prints the configured servers;

mcporter list <server> prints that server's tools. Add --schema (or --all-parameters) for full input parameters, --brief / --signatures for compact one-line signatures, and --status for a health check.

1. Ad-hoc endpoints. For a server not in config: --stdio "<launch command>" targets a

locally-launched stdio server (--stdio "bun run ./srv.ts"); --http-url <url> — or passing the full URL directly as the selector — targets a remote HTTP server. The launch-command flag is --stdio, never --command / --exec / --cmd.

1. OAuth — mcporter auth <server|url>. The browser OAuth flow is the auth subcommand

(mcporter auth notion), not login / oauth / connect. Add --no-browser to print the authorization URL for headless use.

1. Config — mcporter config <list|get|add|remove|import>. Register a server with

config add <name> <url> (append --auth oauth for OAuth); read one entry with config get <name>; delete one with config remove <name>; pull definitions from other clients with config import <cursor|claude-code|codex|...>.

1. Machine-readable output — --output json. Add --output json (or the shorthand --json)

to any command to get JSON; not --format json.

1. Keep-alive pool — mcporter daemon <start|status|stop|restart>. Pre-warm a background

server pool with daemon start, check it with daemon status, and bounce it after config edits with daemon restart.

1. Package a server as a CLI — mcporter generate-cli. mcporter generate-cli --command <url>

(or mcporter generate-cli <server-name>) emits a standalone CLI. Read a generated artifact's build metadata with mcporter inspect-cli <path>.

1. TypeScript codegen — mcporter emit-ts <server> --mode client|types. --mode client

emits a full typed client wrapper; --mode types emits type-only declarations. The flag is --mode, its values client / types — never --type / --target.

1. Config file — config/mcporter.json. By default mcporter reads the project file

config/mcporter.json; override with --config <path> (also honored, in order: $MCPORTER_CONFIG, then $XDG_CONFIG_HOME/mcporter/mcporter.json[c] or ~/.mcporter/mcporter.json[c]).

Worked examples

BEFORE = the wrong default a base model guesses; AFTER = the real mcporter form.

• Calling a tool:
• BEFORE: mcporter call --server github --tool create_issue --title "Bug"
• AFTER: mcporter call github.create_issue title="Bug"
• Structured argument:
• BEFORE: mcporter call slack.post --channel "#general" --text hi
• AFTER: mcporter call slack.post --args '{"channel":"#general","text":"hi"}'
• Inspecting a server's parameters:
• BEFORE: mcporter describe brave-search
• AFTER: mcporter list brave-search --schema
• Local stdio server:
• BEFORE: mcporter call --command "python srv.py" scan path=/x
• AFTER: mcporter call --stdio "python srv.py" scan path=/x
• OAuth sign-in:
• BEFORE: mcporter login sentry
• AFTER: mcporter auth sentry
• Registering a server:
• BEFORE: mcporter add sentry https://mcp.sentry.dev/mcp
• AFTER: mcporter config add sentry https://mcp.sentry.dev/mcp --auth oauth
• JSON output:
• BEFORE: mcporter call weather.today city=NYC --format json
• AFTER: mcporter call weather.today city=NYC --output json
• Keep servers warm:
• BEFORE: mcporter serve --keep-alive
• AFTER: mcporter daemon start
• Packaging a CLI:
• BEFORE: mcporter codegen --url https://mcp.grep.app/mcp
• AFTER: mcporter generate-cli --command https://mcp.grep.app/mcp
• TypeScript client:
• BEFORE: mcporter emit-ts vault --type client
• AFTER: mcporter emit-ts vault --mode client

Edge cases & exceptions

• Shorthand verbs. mcporter <server>.<tool> (a dotted selector) infers call; mcporter <server>

(a bare server name, no dot) infers list. The dot is what distinguishes a call from a list.

• Inline vs --args. Inline key=value is fine for flat scalars; switch to --args '<json>'

the moment a value is an object or array. Do not mix inline and --args for the same key.

• Coercion. Inline values are coerced (numbers, booleans, null, JSON) by default; pass

--raw-strings or --no-coerce to keep them as literal strings.

• URL as selector. A full https://…/mcp URL can stand in for <server> directly in call

and list; --http-url <url> is the explicit equivalent.

• Config precedence. --config > $MCPORTER_CONFIG > project config/mcporter.json >

$XDG_CONFIG_HOME/mcporter/mcporter.json[c] / ~/.mcporter/mcporter.json[c].

Do / Don't

• DO join server and tool with a dot: linear.list_issues. DON'T pass two args or --server/--tool.
• DO pass arguments as key=value / key:value. DON'T use --key value GNU flags for tool arguments.
• DO inspect with mcporter list <server> --schema. DON'T use describe / inspect / tools.
• DO launch a stdio server with --stdio "<cmd>". DON'T use --command / --exec.
• DO run OAuth with mcporter auth <server>. DON'T use login / oauth / connect.
• DO register with mcporter config add <name> <url>. DON'T use mcporter add / register.
• DO request JSON with --output json. DON'T use --format json.
• DO warm servers with mcporter daemon start. DON'T use serve / start / warmup.
• DO code-gen with generate-cli and emit-ts --mode client|types. DON'T use codegen / --type.

Common mistakes

• Splitting server.tool into separate arguments or --server/--tool flags instead of the dotted selector.
• Passing tool arguments as --key value GNU flags rather than key=value / key:value.
• Inventing mcporter describe / mcporter inspect to see a server's tools instead of mcporter list <server> --schema.
• Using --command for a locally-launched server (the flag is --stdio).
• Reaching for mcporter login / mcporter oauth instead of mcporter auth.
• Using mcporter add instead of mcporter config add, or mcporter import instead of mcporter config import.
• Writing --format json for machine output instead of --output json / --json.
• Naming the codegen codegen / build instead of generate-cli, or using --type instead of --mode on emit-ts.

Quick checklist

• ] Tool call: mcporter call <server>.<tool> (dotted selector; call verb or shorthand).
• ] Arguments: key=value / key:value / --args '<json>' / key=@file — never --key value.
• ] Inspect: mcporter list <server> --schema (or --brief / --signatures).
• ] Ad-hoc: --stdio "<cmd>" for local, --http-url <url> or a full URL for remote.
• ] OAuth: mcporter auth <server|url>.
• ] Config: mcporter config add|get|remove|import; register = config add <name> <url>.
• ] JSON: --output json (or --json).
• ] Keep-alive: mcporter daemon start|status|stop|restart.
• ] Codegen: mcporter generate-cli --command <url>; mcporter emit-ts <server> --mode client|types.
• ] Config file default config/mcporter.json; override --config <path>.