How to Run MCP Tools from a Shell¶
Call any Silo MCP tool from a terminal with python -m silo_sdk_mcp --call, with no MCP client involved.
The runner builds the same server the stdio and HTTP transports serve, inside your shell process, and calls one tool. Every tool is available (all 76, including the composite ones such as a8_org_summary). This page is a walkthrough. For the complete option, redaction and exit-code reference, see Running a tool without an MCP client.
When to Use the Runner¶
- No MCP client is available, or the client cannot load the server, for example under a managed MCP policy.
- Scripting. One call, JSON on stdout, a meaningful exit code.
- Checking a tool's behavior before an agent or client relies on it.
If a dedicated script already covers the job, it is usually the better fit. See The Runner Versus the Scripts.
Setup¶
The runner needs the mcp-server extra. From a repository checkout, with your virtual environment active:
Configuration is read exactly as in stdio mode. Credentials come from .env and config/, and A8_CONFIG_ENV chooses a profile:
See Configuration for the profile files and the A8_* settings. With no profile set, the base .env and config/default.json apply, and the runner reports the profile as base.
Find a Tool and Its Arguments¶
List every tool with its kind:
Authentic8 MCP Server - 76 tools
==================================================
Browsing Isolation (7 tools)
----------------------------------------
a8_create_context [write]
a8_get_context [read]
a8_update_context [write]
a8_delete_context [destructive]
a8_list_egress_locations [local]
...
| Mark | Meaning | Needs --yes |
|---|---|---|
[read] |
Reads from the Silo API. | No |
[local] |
Answers from the SDK itself and makes no API call. | No |
[write] |
Changes Silo state. | Yes |
[destructive] |
Deletes, replaces or invalidates something, or can run arbitrary commands (a8_batch_request). |
Yes |
The three tools that only write a local file (a8_download_file, a8_download_harvest_result, a8_export_logs_csv) are marked [read] because they change nothing in Silo.
Describe a tool before calling it¶
--describe prints one tool's description and every argument's type, whether it is required, its default, its limits and its format, with an example. It reads the same schema an MCP client receives, makes no API call and needs no credentials:
a8_extract_logs [read]
======================
Extract audit logs from a Silo organization.
...
Arguments (3 required, 9 optional):
org (string; required)
Required. API org name to extract logs from, e.g. `ExampleOrg` -- the org name,
not its vanity URL.
start_seq (integer; required; >= 0)
Required. Log sequence number to start from, an integer >= 0. `0` starts at the
earliest log still held; `a8_get_extract_logs_info` returns it as `min_seq`; to
page, pass the previous response's `next_seq`.
...
limit (integer | null; optional; >= 1; <= 1000)
Optional. Maximum rows per call, 1-1000 (server default when omitted). Capped
lower automatically when `ENC` is requested.
start_date (integer | null; optional; >= 0; e.g. 90)
Optional. Earliest day to include, as an **integer number of days before today**
(`90` = from midnight UTC 90 days ago, `0` = today). Not a date and not an epoch
timestamp -- `"2026-07-01"` and `1783468800` both fail.
...
Required arguments are listed first. --describe cannot be combined with --call, --args, --args-file, --yes, --reveal, --list-tools or the server options. It exits 0, or 2 for an unknown tool name.
When a call does fail on its arguments, the error names each bad argument, what was wrong with it and the same description, and ends with the --describe command to run:
a8_extract_logs failed: Invalid arguments for a8_extract_logs:
- start_seq: required, but not given. Expected integer; >= 0. Required. Log sequence number to start from, ...
Every argument's type and format: python -m silo_sdk_mcp --describe a8_extract_logs
Argument gotchas¶
These rules have each cost someone a failed call. --describe states all of them; this table collects them.
| Tool | Argument | Rule |
|---|---|---|
a8_get_session_report |
user_id, username, org_id, org_name, hierarchy |
At most one. Passing two fails with "Only one identifier may be provided". Pass none to report on the token's own org. |
a8_get_session_report |
start_date, end_date |
MM-DD-YYYY strings, such as 10-01-2026. ISO 2026-10-01 is refused. |
a8_get_session_report |
(result) | Aggregates only: session_count, session_secs, average_session_secs, longest_session_secs, shortest_session_secs, user_count. For individual sessions, use a8_extract_logs with SESSION. |
a8_extract_logs |
start_seq |
Required. 0 starts at the earliest log still held. a8_get_extract_logs_info returns that point as min_seq. |
a8_extract_logs, a8_stream_logs, a8_export_logs_csv |
start_date, end_date |
Integers counting days before today (90 = 90 days ago), not dates. An ISO date or an epoch timestamp fails. end_date is converted to midnight UTC, so 0 excludes today; leave it out to include everything up to now. |
a8_extract_logs |
limit |
1 to 1000. |
a8_extract_logs |
(paging) | While the result has is_more: true, call again with the same arguments and start_seq set to the result's next_seq. a8_stream_logs and a8_export_logs_csv do this for you. |
a8_extract_logs |
log_types |
SESSION holds where a session ran and connected (egress_location, execution_server_name, toolbox_name). LOCATION_CHANGE is page navigation: each row is a URL the user visited. Treat the URL-bearing types (URL, LOCATION_CHANGE, BLOCKED_URL, POST_DATA, COOKIES, ENC and similar) as sensitive. |
a8_extract_logs |
(users) | There is no user filter. Extract the org and filter rows on username. |
| User tools and org tools | org / org_name |
User and log tools take org; org tools (a8_get_org, a8_org_summary, ...) take org_name. Both mean the API org name, not the vanity URL. |
a8_create_context, a8_create_browsing_url |
username, org |
Exactly one. Here org is the org's vanity URL slug, unlike the user and log tools. |
a8_create_context, a8_update_context |
max_uses |
An integer of 1 or more; 0 is refused. To switch a context off, pass enabled: false. |
a8_create_context, a8_create_browsing_url, a8_update_context |
expires |
A string. Quote an epoch ("1767225600"); a bare JSON number is refused. |
a8_create_harvest_task, a8_harvest_url |
urls, run_after |
urls is a list holding exactly one URL. run_after is an epoch integer or an ISO string in exactly YYYY-MM-DDTHH:MM:SSZ form. |
a8_get_user, a8_promote_user_to_admin |
username, email |
One or the other, not both. a8_modify_user looks the user up by email. |
Read Examples¶
A local tool¶
Local tools are the safest way to confirm the runner works, because they call no API. This run used a placeholder token against an Eng URL (example.com stands in for the real host). Your sdk_version, URL and other values will differ:
Target: https://extapi.eng.example.com (eng), profile base, tool a8_get_api_info [local]
{
"api_url": "https://extapi.eng.example.com",
"sdk_version": "0.16.1",
"tool_count": 76,
"top_org": null,
"environment": "eng",
"bucket_id_configured": false
}
The Target: line goes to stderr and the JSON to stdout. Another local tool, a8_validate_config, reports which settings are missing without contacting the API:
It prints valid, missing, present, optional_missing and api_url. With only API_URL and ADMIN_TOKEN set, valid is false and missing lists SYNC_TOKEN, FILE_TOKEN, LOG_TOKEN, SCRAPE_TOKEN, BUCKET_ID and TOP_ORG.
Read tools¶
These call the API using the tokens in your configuration. MyOrg is a placeholder; use an org you own.
# One organization
python -m silo_sdk_mcp --call a8_get_org --args '{"org_name": "MyOrg"}'
# Users in an organization
python -m silo_sdk_mcp --call a8_list_users --args '{"org": "MyOrg"}'
# One-call summary; leave out the parts you do not need
python -m silo_sdk_mcp --call a8_org_summary \
--args '{"org_name": "MyOrg", "include_users": false}'
# Probe every configured token (takes no arguments)
python -m silo_sdk_mcp --call a8_health_check
a8_health_check lists each configured token with its status, so it is a quick way to see which credentials work before a longer job.
Pass Arguments¶
Arguments are one JSON object. Give it inline with --args, or from a file with --args-file. The two options cannot be combined (exit 2), and with neither the arguments default to {}.
In a POSIX shell, wrap the JSON in single quotes so the double quotes inside survive:
In PowerShell, quoting JSON is fragile, so prefer --args-file. Quoting is also easier to get right in a file for anything longer than a field or two:
cat > args.json <<'EOF'
{"org_name": "MyOrg", "include_users": false, "max_users": 25}
EOF
python -m silo_sdk_mcp --call a8_org_summary --args-file args.json
The value must be a JSON object. An array, malformed JSON, an empty --args "" or an unreadable file exits 2 before any tool runs. An argument name the tool does not accept also exits 2, so a typo never reaches the API as a silently ignored field. The message lists the valid names and points at --describe, which shows their types and formats.
Write Examples¶
Any tool that is not [read] or [local] is refused unless you pass --yes. Without it, nothing is sent:
Target: https://extapi.eng.example.com (eng), profile base, tool a8_suspend_user [write]
... ERROR: a8_suspend_user changes Silo state on eng; re-run with --yes to proceed.
The command exits 2. Reading that output is the confirmation step. Before adding --yes, check the Target: line, which names:
- the API URL, without any credentials embedded in it,
- the environment:
eng,qaorproduction. A URL that cannot be classified is reported asproduction, so an unrecognized target is never taken for a safe one, - the profile (
A8_CONFIG_ENV, orbase), and - the tool and its kind.
The Target: line does not show the organization. The org you act on is decided by the tokens in the profile, so check that they belong to the org you mean to change. production is normal for a demo org on the production API, but a write against a non-demo production org deserves extra care.
Always run a write tool once without --yes first. That refused run is the only preview the runner offers: it prints the Target: line and refuses before any API call.
If the environment or profile is not the one you meant, stop and fix A8_CONFIG_ENV. Then run it for real:
Try writes on Eng or a demo org first
--yes takes effect immediately, and [destructive] tools such as a8_delete_user cannot be undone. Rehearse a new call against an Eng profile or a demo org, and only then repeat it where it matters.
Tools That Return a New Credential¶
Three tools return a credential that exists only in their result:
| Tool | Returns |
|---|---|
a8_reset_pin |
the new temporary password (the old PIN is gone) |
a8_add_user |
the new user's bypass code |
a8_bulk_add_users |
a bypass code for each created user |
a8_batch_request is treated the same way when its commands include reset_pin or adduser, and also when commands cannot be inspected as a list.
Redaction would hide those values after the change is already made, and the credential could not be recovered. So the runner refuses these tools unless you pass both --yes and --reveal:
--reveal prints a warning on stderr and turns redaction off for the whole result. Handle the output carefully:
- Print it to your own terminal, or redirect it to a file only you can read. Do not paste it into tickets, chat or logs.
- Hand the credential to its owner through your normal secure channel, and delete any file that held it.
- Use
--revealonly when you need a value that is itself a credential. Leave it off for everything else.
Read the Output¶
The result is JSON on stdout. The Target: line, the --reveal warning, log lines and errors go to stderr, so you can pipe stdout without them:
To keep stderr out of the way as well, add 2>/dev/null (or 2>$null in PowerShell). Do that only once the call works, because it also hides errors.
By default the runner redacts credentials, printing <redacted> in place of the value. The structure is kept, so the result still has the same shape. Redaction hides:
- string values under credential-named keys: names ending in
token,key,auth,password,secret,credential,passwdorsession_id(plural forms count), and names containingpassword,passwd,secret,credential,authorization,cookie,bearer,jwt,private_keyorbypass_code, - credential headers (
Authorization,Cookie,X-Api-Keyand similar) and credential-bearingpost-datain harvest tasks, and - any configured token value of 8 or more characters, wherever it appears in a string.
Descriptive fields such as key_name, token_type and auth_method are left alone. The reference section lists the exact rules.
Redaction applies only to what the runner prints.
File tools and MCP_FILE_ROOT
File tools read and write local paths only inside the directories named by MCP_FILE_ROOT, as in server mode (see Local File Access). If it is unset, the root is a silo_sdk_mcp_files directory under the system temporary directory. a8_download_file writes there, with relative paths anchored to the first root, and a8_download_harvest_result and a8_export_logs_csv default to it when output_path is omitted.
Logging defaults to WARNING with --call and --describe, so stderr is quiet apart from the Target: line. Use --log-level DEBUG when diagnosing a failure.
Exit Codes¶
| Code | Meaning |
|---|---|
0 |
The tool ran. A tool that returns false or "not found" is still 0; check the JSON. |
1 |
The tool failed (an API error, a missing token, invalid tool arguments). |
2 |
A usage or configuration problem: unknown tool (including with --describe), bad --args, unknown argument name, invalid server setting, or a refusal for a missing --yes or --reveal. |
In a script, test the code rather than parsing stderr:
if out=$(python -m silo_sdk_mcp --call a8_get_org --args '{"org_name": "MyOrg"}' 2>/dev/null); then
echo "$out" | jq .
else
echo "lookup failed (exit $?)" >&2
fi
A 0 with a false or empty result means the tool answered and the answer was "no". Check the content when that distinction matters to your script.
Troubleshooting¶
Log lines on stderr start with a timestamp and [silo_sdk_mcp] ERROR:. The messages below are shown without that prefix.
| Message | Meaning and fix |
|---|---|
Unknown tool: a8_nope. List them with --list-tools. (exit 2) |
The name is not registered. Copy it from --list-tools. |
Unknown argument(s) for a8_get_valid_task_types: bogus. Valid: (none). Types and formats: --describe a8_get_valid_task_types. (exit 2) |
The tool does not accept that key. The message lists the valid names, or (none). |
a8_extract_logs failed: Invalid arguments for a8_extract_logs: ... (exit 1) |
An argument is missing, has the wrong type or is out of range. Each bad argument gets one line with the expected type, limits and format. Run --describe on the tool. |
--describe cannot be combined with ... (exit 2) |
--describe only prints. Drop --call, --args, --yes and the other options. |
--describe needs a tool name. (exit 2) |
Pass a name from --list-tools. |
a8_delete_user changes Silo state on eng; re-run with --yes to proceed. (exit 2) |
The tool is [write] or [destructive]. Check the Target: line, then add --yes. |
a8_reset_pin returns a new temporary credential that output redaction would hide; re-run with --yes --reveal. (exit 2) |
The tool returns a new credential. See Tools That Return a New Credential. |
Cannot read the --call arguments: ... (exit 2) |
--args is not valid JSON, is empty, or --args-file cannot be read. The detail after the colon names the cause. |
The --call arguments must be a JSON object. (exit 2) |
The JSON parsed but is not an object, for example an array. |
Invalid server settings: ... (exit 2) |
An MCP_* setting, such as MCP_MAX_WAIT_SECONDS, has an invalid value. The text names the setting. |
Configuration error: ... (exit 2, at startup) |
.env or config/ could not be loaded, for example an invalid A8_CONFIG_ENV profile name. |
--call cannot be combined with --list-tools or the server options ... (exit 2) |
--call runs one tool and exits. Drop --transport, --host, --port, --credentials, --ssl-* or --list-tools. |
--call needs a tool name. (exit 2) |
--call was given an empty or blank name. Pass a name from --list-tools. |
--yes only applies with --call. (exit 2) |
--args, --args-file, --yes and --reveal mean nothing without --call. |
Configuration error: Missing required configuration: SYNC_TOKEN (set A8_SYNC_TOKEN) (exit 1) |
The tool needs a token that is not configured. The full line is prefixed by a8_list_users failed: and the MCP library's "Error executing tool" wording. A missing token appears as a tool error, not a usage error. Set the named A8_* variable, or run a8_validate_config to see everything that is missing. |
Other tool failures also exit 1 and read <tool> failed: <reason>, where the reason is the one an MCP client would see. Configured token values are scrubbed from it unless you passed --reveal.
The Runner Versus the Scripts¶
The runner and the scripts in scripts/ reach the same API. Choose by the job:
| Use the runner when | Use a script when |
|---|---|
| No script covers the operation. | A script exists for the task, such as reports.py, contexts.py or file_manager.py. |
You want one call, or a tool's composite logic (a8_org_summary, a8_harvest_url). |
You need the script's own flags, bulk input, output formats or resume behavior. |
| You are checking what an MCP client would get back. | You are building something repeatable around a task. |
| The call must go through the same redaction and confirmation rules as the MCP server. | You want a dry run, which several scripts offer and the runner does not. |
The scripts are documented in Examples & Scripts, which also covers the confirmation flags (--yes) their state-changing subcommands share with the runner.