Skip to content

`maqpna call`

Make one tool call through the gateway with a session token (debugging)

Run agents-o json | yaml

Synopsis#

maqpna call [--gateway URL] --server S --tool T [--arg K=V]... [--args JSON|@FILE] [--token-file F] [--header NAME:VALUE]... [--timeout 5m30s] | --list

Description#

The call is governed exactly like the agent's own: policy, DLP, taint, approvals, budgets and audit. Under "maqpna dev run" the gateway URL and the session token come from the environment (MAQPNA_GATEWAY_URL, MAQPNA_TOKEN). In a cluster, get a session's token with

  kubectl get secret SESSION-maqpna-token -n NS -o jsonpath='{.data.token}' | base64 -d > tok

Exit status: 0 the tool returned a result, 3 the gateway refused the call (JSON-RPC error: policy denied, approval pending, revoked, DLP) or the tool reported isError, 1 transport or authentication errors.

Flags#

Flag	Type	Description	Default
`--arg`	string	one tool argument KEY=VALUE (repeatable; VALUE is JSON if it parses, else a string); merged over `--args`	none
`--args`	string	tool arguments as a JSON object (@FILE reads a file)	`{}`
`--gateway`	string	gateway base URL (env MAQPNA_GATEWAY_URL)	none
`--header`	string	extra request header NAME:VALUE (repeatable; e.g. traceparent)	none
`--list`	switch	list the server's tools (tools/list) instead of calling one	none
`--server`	string	MCP server name (the gateway route /mcp/SERVER)	none
`--timeout`	duration	how long to wait for the result; a call held for approval waits up to the gateway's approval timeout (300s by default, as in maqpna dev up)	`5m30s`
`--token`	string	session token (env MAQPNA_AGENT_TOKEN, else MAQPNA_TOKEN as maqpna dev run and sandboxes set it); `--token-file` is safer	none
`--token-file`	string	file with the agent's session token (a session's <name>-maqpna-token Secret, key token)	none
`--tool`	string	tool name	none

The global flags (--context, -o, --no-color, ...) work with every command.

Examples#

# Under maqpna dev run: the gateway and session token come from the environment
$ maqpna dev run -- maqpna call --server echo --tool echo --arg text=hello
$ maqpna call --gateway https://gateway.example.eu --token-file tok --server echo --list
$ maqpna call --gateway https://gateway.example.eu --token-file tok --server github --tool create_issue --args @issue.json

What happens when you run it#

Talks to the gateway: --gateway, else MAQPNA_GATEWAY_URL, else the current context's gateway (maqpna context).
Authenticates to the admin API with the token stored by maqpna login, --oidc-token-file, or a static --token (MAQPNA_ADMIN_TOKEN).
Prints a table by default; -o json or -o yaml print the data, and --jq EXPR filters the JSON.

Exit codes#

Code	Meaning
`0`	success
`1`	error (the message says what failed, with a hint when there is one)
`2`	usage error: unknown flag, missing argument or bad value; the synopsis is printed
`3`	a check failed, a change is blocked, or a result did not match (tamper, policy mismatch) (not used by this command)

Terminal demo#

maqpna call.cast