MCP Server Overview¶
The Authentic8 MCP Server exposes the entire Silo SDK as 75 structured tools that AI assistants can invoke directly through the Model Context Protocol.
Quick start for most users
If you're using Claude Desktop or Claude Code, jump straight to Setup. The remote (HTTP) tab is only needed for team deployments.
What is MCP?¶
Model Context Protocol (MCP) is an open standard for connecting AI assistants to external tools and data sources. The Authentic8 MCP Server implements this protocol, allowing AI assistants like Claude Desktop, Cursor, and other MCP-compatible clients to:
- Manage Silo browsing isolation contexts
- Upload, download, and organize files in Silo storage
- Create and monitor web harvesting tasks
- Administer user accounts and organizations
- Extract and decrypt audit logs
Instead of writing SDK wrapper code, you describe what you want and the AI calls the appropriate tool automatically.
Architecture¶
The MCP server is a thin wrapper around the SDK. Each SDK method becomes an MCP tool with the same parameters and return types.
flowchart TD
A["<b>AI Assistant</b><br/>Claude · Cursor · other MCP clients"]
B["<b>Authentic8 MCP Server</b><br/>━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━<br/><b>Tool Registry — 76 tools</b><br/><code>a8_create_context</code> · <code>a8_list_users</code> · <code>a8_upload_file</code><br/><code>a8_extract_logs</code> · <code>a8_health_check</code> · <i>71 more</i>"]
C["<b>Silo SDK</b><br/>━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━<br/>BrowsingAPI · UserManagementAPI · OrgManagementAPI<br/>FileAPI · LogExtractionAPI · HarvesterAPI"]
D["<b>Authentic8 Silo API</b><br/>extapi.authentic8.com"]
A -->|"MCP Protocol (JSON-RPC)"| B
B -->|"SDK method calls"| C
C -->|"HTTPS"| D
style A fill:#e8f4fd,stroke:#1976d2,color:#0d1117
style B fill:#fff8e1,stroke:#f57c00,color:#0d1117
style C fill:#e8f5e9,stroke:#388e3c,color:#0d1117
style D fill:#fce4ec,stroke:#c62828,color:#0d1117
Transport Modes¶
The MCP server supports two deployment patterns:
stdio (Local)¶
- Use case: Individual developers with their own credentials
- Client: One AI assistant per server process
- Credentials: Loaded from
.envfile or environment variables - Connection: AI assistant spawns server as subprocess, communicates via stdin/stdout
- Best for: Claude Desktop, Claude Code, local development
HTTP (Remote)¶
- Use case: Team environments with shared infrastructure
- Client: Multiple AI assistants connect to one server
- Credentials: Per-client credential store (
credentials.yaml) - Connection: HTTP server at
http://host:8080/mcp(orhttps://when TLS is enabled) (--transport streamable-http), clients authenticate with Bearer tokens - Best for: Production deployments, multi-tenant environments
sse is the legacy transport
--transport sse is still accepted and serves at /sse instead of /mcp. It remains
available for older clients that cannot speak Streamable HTTP; use streamable-http
for anything new.
Available Tools¶
The MCP server provides 76 tools organized by API category.
Every tool declares what it does to the platform through MCP tool annotations, so a client can tell reads from writes and ask before changing anything:
| Kind | Annotations | Meaning |
|---|---|---|
| read | readOnlyHint: true |
Calls the API and changes nothing |
| local | readOnlyHint: true, openWorldHint: false |
Makes no API call (static data, configuration checks) |
| write | readOnlyHint: false, destructiveHint: false |
Creates or changes something |
| destructive | readOnlyHint: false, destructiveHint: true |
Deletes, replaces or invalidates something, or can run arbitrary commands |
python -m silo_sdk_mcp --list-tools shows each tool's kind, and --call refuses any tool that is
not read-only unless --yes is given (see
Running a tool without an MCP client). The three tools that
only write a local file (a8_download_file, a8_download_harvest_result, a8_export_logs_csv)
are marked read-only because they change nothing on the platform.
Browsing Isolation (7 tools)¶
| Tool | Description |
|---|---|
a8_create_context |
Create a secure browsing isolation context; returns browse_context_id and launch_url |
a8_get_context |
Retrieve context details |
a8_update_context |
Update context properties (max_uses, name, expires, enabled, context_data) |
a8_delete_context |
Delete a browsing context |
a8_create_research_session |
Create a Silo for Research context with egress selection, connectivity, browser profile, and protocol options |
a8_list_egress_locations |
List egress locations by region; returns enriched connectivity, availability, and protocol metadata by default (include_details=True) |
a8_list_egresses |
Ask the platform which egresses an account can actually use; reflects entitlements, org policy, and which egresses are up, so prefer it over the static list; service_type="harvest-asset" reports the asset harvest pool |
a8_create_research_session parameters
In addition to url, username, egress_region, and max_uses, this tool accepts:
connectivity—"datacenter","isp","fixed-wireless", or"wireless-carrier"availability—"public"or"private"protocol—"direct","tor", or"sovereign"(in-country egress for data-residency requirements, provisioned per org fortoolbox-standalonesessions; calla8_list_egresseswithsession_type="toolbox-standalone"to find the org's sovereign locations, or useegress_region="World"to let the platform choose)browser_os—"win","mac","linux","android","android phone","ios","iphone","ipad"browser_type—"chrome","firefox","edge","safari","tor"
When max_uses is omitted, the tool reads DEFAULT_MAX_USES from configuration
(set via A8_DEFAULT_MAX_USES env var; defaults to 1). See
Configuration for details.
File Storage (8 tools)¶
| Tool | Description |
|---|---|
a8_upload_file |
Upload a file from a local path (file_path) or inline string (content). bucket_id defaults to the configured BUCKET_ID when omitted. |
a8_download_file |
Download a file to a specified path or temp directory (auto-generates filename from metadata when output_path omitted) |
a8_read_file_content |
Download a small file (< 1 MB) and return its text content directly |
a8_find_files |
Search for files by name, path, type, date, size, or metadata |
a8_list_files |
List all files in a bucket |
a8_modify_file |
Change file name, path, expiry, or content type |
a8_delete_file |
Delete a file |
a8_get_file_info |
Get detailed file information |
Web Harvesting (9 tools)¶
| Tool | Description |
|---|---|
a8_create_harvest_task |
Create a harvest task (asset/visual/video/single/wget) |
a8_find_harvest_task |
Get task status and details |
a8_list_harvest_tasks |
Look up multiple tasks by ID with optional status/finished filters |
a8_delete_harvest_task |
Delete a harvest task |
a8_wait_for_harvest_task |
Poll until a task completes or times out |
a8_download_harvest_result |
Download the output ZIP to a path under MCP_FILE_ROOT (saves as harvest_<task_id>.zip in the first root when omitted) |
a8_get_valid_task_types |
List valid task type strings |
a8_get_valid_task_params |
List valid parameters for a given task type |
a8_list_egress_categories |
List egress location availability by task type (asset-restricted) |
User Management (13 tools)¶
| Tool | Description |
|---|---|
a8_list_users |
List all users in an organization |
a8_get_user |
Get user details (by username or email) |
a8_find_user |
Search users by partial email or name (case-insensitive) |
a8_add_user |
Add a new user; returns the existing user record with _already_exists=true and _hint if the user already exists |
a8_bulk_add_users |
Add multiple users in a single call with per-user error tolerance; returns created, failed, results, and errors counts |
a8_modify_user |
Modify user attributes |
a8_delete_user |
Delete a user |
a8_suspend_user |
Suspend a user account |
a8_unsuspend_user |
Restore a suspended account |
a8_unlock_user |
Clear a user's failed-login and out-of-band lockouts |
a8_reset_pin |
Reset PIN / generate temporary password |
a8_promote_user_to_admin |
Promote a user to admin for an organization |
a8_list_users_recursive |
Recursively list users across an org and all sub-orgs |
Organization Management (23 tools)¶
| Tool | Description |
|---|---|
a8_get_org |
Get organization details |
a8_get_org_children |
List sub-organizations (pass recursive=true to get flat list of all descendants) |
a8_create_org |
Create a new organization; returns the existing org record with _already_exists=true and _hint if the org already exists |
a8_update_org |
Update organization properties |
a8_delete_org |
Delete an organization |
a8_get_session_report |
Get session/isolation usage report |
a8_org_usage_report |
Org-level usage report across hierarchy (provisioned users, active users, session counts, duration stats) |
a8_user_usage_report |
Per-user usage report across hierarchy (username, session counts, duration stats) |
a8_create_partner_sso_config |
Create org with federated SSO (IdP partner) |
a8_get_partner_sso_config |
Get SSO configuration |
a8_get_sso_policy |
Get the SAML SSO policy for an org — the policy-side view, readable for an org with plain SAML SSO and no Partner SSO |
a8_update_partner_sso_config |
Update SSO configuration |
a8_enable_partner_sso_config |
Enable SSO |
a8_disable_partner_sso_config |
Disable SSO |
a8_delete_partner_sso_config |
Delete SSO config and associated org |
a8_get_proxy_policy |
Get proxy objects for an org |
a8_set_proxy_policy |
Replace the entire proxy list for an org |
a8_add_proxy_policy |
Append proxy objects to an org's policy |
a8_delete_proxy_policy |
Remove named proxy objects from an org |
a8_clear_proxy_policy |
Fetch all proxy objects and delete them in one call |
a8_parse_saml_metadata |
Parse SAML IdP metadata XML into structured config |
a8_get_org_tree |
Return the full org hierarchy as a nested dict |
a8_resolve_org |
Resolve an ambiguous org name to its canonical full path |
Log Extraction (4 tools)¶
| Tool | Description |
|---|---|
a8_extract_logs |
Extract audit logs by type and sequence |
a8_get_log_sequence_info |
Get available log sequence metadata |
a8_get_valid_log_types |
List the log types the platform supports; falls back to the SDK's built-in list if the platform can't be reached |
a8_get_extract_logs_info |
Get log sequence info via extractlog probe |
Valid log types (26): A8SS, ADMIN_AUDIT, APP_LAUNCH, AUTH, BLOCKED_URL,
CASE_MANAGER, CLIPBOARD, COOKIES, DOWNLOAD, ENC, EVENT, EXPLOIT,
EXTENSION, HARVEST, ISOLATE_BYPASS, LAUNCHER, LOCATION_CHANGE, NEXUS,
POST_DATA, PRINT, SESSION, SMS, TRAFFICMAN, TRANSLATION, UPLOAD, URL
Note
Four log types use spaces on the wire: BLOCKED URL, CASE MANAGER,
LOCATION CHANGE, POST DATA. Pass the underscore form — the SDK converts
automatically.
Note
ENC (encrypted) entries have no fixed field structure. All other 25 types have
canonical CSV column schemas used by a8_export_logs_csv to determine column order.
a8_extract_logs advanced parameters
The backend serializes log extraction and may return a lock-contention error when multiple jobs run concurrently. Optional parameters for resilience:
retry_on_lock— Settrueto retry automatically on lock contention (default:false)retry_delay— Seconds to wait between retries (default:60)max_retries— Maximum number of retry attempts (default:3)fallback_per_type— Settrueto retry each log type individually when the combined request fails; results are aggregated and any per-type errors appear in thetype_errorsfield of the response (default:false). On a fallback response,next_seqis the lowest resume point among the types that still report more, so the next page can repeat rows — deduplicate byseq_id. Types intype_errorsare not covered bynext_seq; re-request them from the originalstart_seq.
Batch Requests (3 tools)¶
| Tool | Description |
|---|---|
a8_batch_request |
Execute multiple wire-format commands in a single batch POST; token_type selects which token authenticates the batch |
a8_batch_suspend_users |
Suspend multiple users in a single API round-trip |
a8_batch_delete_users |
Delete multiple users in a single API round-trip; known API false-errors are surfaced as "deleted (unconfirmed)" with a verification note |
Diagnostics (4 tools)¶
| Tool | Description |
|---|---|
a8_health_check |
Probe all 5 tokens with lightweight API calls; returns per-token status, latency (ms), and the list of tools available for each healthy token |
a8_validate_config |
Check all required config keys without making API calls; lists missing, present, and optional keys |
a8_get_api_info |
Return API endpoint URL, SDK version, total tool count, detected environment (prod/qa/eng), and bucket configuration status |
a8_debug_payload |
Show the wire-format JSON payload for any command with token redacted — no API call made |
Compound Workflows (5 tools)¶
| Tool | Description |
|---|---|
a8_harvest_url |
Create a harvest task, wait for completion (up to max_wait_seconds; default 1800), and return task status and result_file_id in a single call |
a8_create_browsing_url |
Create an isolation context and return the launch_url directly; accepts all a8_create_context parameters except auto_domain_allow, including optional egress_info, which cannot be combined with egress_region or categories |
a8_org_summary |
Rich one-call org summary: org info, user list, child orgs, and proxy policies; partial results returned if any section fails |
a8_stream_logs |
Auto-paginate log extraction using is_more/next_seq until all pages are retrieved; enforces a 10,000-log cap (truncated: true when hit) |
a8_export_logs_csv |
Auto-paginate log extraction and write all rows to a local CSV file under MCP_FILE_ROOT; cap defaults to 100,000 rows; returns output_path, total_rows, columns, and truncated |
Error Handling and Resilience¶
The MCP server includes structured error handling across all tools:
- Mapped errors: SDK exceptions are converted to
ValueError(bad parameters or configuration) orRuntimeError(API failures), each with an actionable message explaining what to check or try next. - Idempotency hints:
a8_add_useranda8_create_orgcatch "already exists" responses and return the existing resource with_already_exists: trueand a_hintfield instead of raising an error. This allows agent workflows to proceed without explicit duplicate checks. - Rate limit retry:
a8_extract_logsand log sequence tools automatically retry once on rate limit errors before surfacing the failure. - Lock contention retry:
a8_extract_logsacceptsretry_on_lock=trueto automatically retry when the backend returns a concurrent-extraction lock error. The lock expires after 10 minutes;retry_delay(default 60s) andmax_retries(default 3) are configurable. - Per-type fallback:
a8_extract_logsacceptsfallback_per_type=trueto retry each log type individually when a combined request fails, aggregating partial results and reporting per-type errors in thetype_errorsfield. - Input sanitization: Tools that accept
orgortask_idstrings reject blank or whitespace-only values with a clearValueErrorbefore making any API call.
Security¶
Credential Safety
Never commit .env, credentials.yaml, or any files containing real API tokens. These files are gitignored by default.
- Token scope: Each API category requires specific tokens (ADMIN_TOKEN, SYNC_TOKEN, FILE_TOKEN, etc.). Tools that lack the required token will raise
ConfigurationErrorwhen invoked. - HTTP mode: In production, serve the HTTP endpoint over HTTPS, either from the server itself (see TLS (HTTPS)) or behind a reverse proxy that terminates TLS.
- Network: The MCP server makes outbound HTTPS calls to
extapi.authentic8.com. Ensure network egress is permitted. - HTTP mode credential scope: An instance serves exactly one client's credentials and refuses to start if
credentials.yamllists more than one. Serving several clients means one instance per client, behind a gateway that routes each Bearer token to its own instance. See Setup for details.
Next Steps¶
Setup Guide — covers both local (stdio) and remote (HTTP) deployment modes
CLI Reference¶
After installing with pip install "silo-sdk[mcp-server]", the silo-sdk-mcp command is available directly in your virtual environment:
Alternatively, invoke via the Python module:
Upgrading from 0.13.x
The Python package was renamed silo_mcp → silo_sdk_mcp in 0.14.0, with no
compatibility shim. An existing checkout needs a reinstall, and HTTP deployments
need their credentials.yaml moved by hand. See
Upgrading from 0.13.x.
Options:
--transport {stdio,sse,streamable-http}- Transport mode (default: stdio)--host HOST- HTTP server bind address (default: 0.0.0.0, i.e. every interface)--port PORT- HTTP server port (default: 8080)--credentials PATH- Path to credentials.yaml, HTTP transports only (default:credentials.yamlnext to the installedsilo_sdk_mcppackage, not the current working directory)--ssl-certfile PATH- PEM server certificate; with--ssl-keyfile, serves HTTPS (env:MCP_TLS_CERTFILE)--ssl-keyfile PATH- PEM private key for the certificate, not passphrase-protected (env:MCP_TLS_KEYFILE)--ssl-client-ca PATH- PEM CA bundle; when set, clients must present a certificate it signed (mutual TLS); requires--ssl-certfileand--ssl-keyfile(env:MCP_TLS_CLIENT_CA)--list-tools- Print all registered tools and exit--describe TOOL- Print one tool's description and each argument's type, required flag, default, limits and format, from the schema clients receive, and exit. Makes no API call and needs no credentials; see Running a tool without an MCP client--call TOOL- Call one tool in-process, print its JSON result and exit; see Running a tool without an MCP client--args JSON/--args-file PATH- The tool's arguments as a JSON object, inline or from a file (default:{});--callonly--yes- Confirm a tool that changes Silo state;--callonly--reveal- Print the result without redacting credentials;--callonly--log-level {DEBUG,INFO,WARNING,ERROR}- Logging level (default: INFO, or WARNING with--callor--describe)
The --ssl-* options apply to the HTTP transports only. With --transport stdio they exit with an error, and the MCP_TLS_* variables are ignored. See TLS (HTTPS).
The default --host binds every interface
0.0.0.0 is the default because the server normally runs inside a container, where
the container runtime decides what is published. Running it directly on a host with
the default reaches the whole network, over plain HTTP unless TLS is configured. Pass
--host 127.0.0.1 (or publish only to loopback in Docker), and for anything that needs
to be reachable off the machine either serve HTTPS from the server
or put a TLS-terminating reverse proxy in front.
Examples:
# List all available tools
silo-sdk-mcp --list-tools
# Start stdio server (for Claude Desktop integration)
silo-sdk-mcp --transport stdio
# Start an HTTP server on port 8080
silo-sdk-mcp --transport streamable-http --port 8080
--transport sse also works, but Streamable HTTP supersedes it — prefer
streamable-http for anything new.
Running a tool without an MCP client¶
--call runs any one tool from a shell, in-process, with the same code the stdio and HTTP
transports serve. Use it where no MCP client can load the server, or to script a single call.
Configuration comes from .env and A8_CONFIG_ENV, exactly as in stdio mode. For a step-by-step walkthrough, see Run MCP Tools from a Shell.
# A read-only tool
python -m silo_sdk_mcp --call a8_get_org --args '{"org_name": "MyOrg"}'
# A tool that changes Silo state needs --yes
python -m silo_sdk_mcp --call a8_delete_user --args '{"username": "jdoe"}' --yes
Before the call, a Target: line on stderr names the API URL (without any embedded credentials), its environment, the profile
and the tool's kind (read, local, write or destructive). The result is printed as JSON
on stdout. --call cannot be combined with --list-tools or the server options (--transport,
--host, --port, --credentials, --ssl-*).
- Confirmation. Any tool that is not read-only is refused unless you pass
--yes. - Describing a tool.
--describe TOOLprints the tool's description and, for each argument, its type, whether it is required, its default, its limits (such as>= 1; <= 1000) and its format with an example. It reads the publishedinputSchema, the same one an MCP client gets, so it cannot drift from the server. It makes no API call, needs no credentials, and cannot be combined with--call,--args,--args-file,--yes,--reveal,--list-toolsor the server options. It exits0, or2for an unknown tool. - Argument names. A key in
--argsthat the tool does not accept is refused (exit2), with the valid names listed, rather than silently ignored. - Argument errors. A missing, mistyped or out-of-range argument fails the call (exit
1) with one line per bad argument: what was wrong, the expected type and limits, and the argument's description. MCP clients receive the same text. - New credentials.
a8_reset_pinreturns a newly generated temporary password, anda8_add_useranda8_bulk_add_usersreturn each new user'sbypass_code; redaction would hide the value after the change is already made. These tools are refused unless you pass both--yesand--reveal. So isa8_batch_requestwhen itscommandsinclude areset_pinoraddusercommand. - Exit codes.
0success;1the tool failed;2a usage error, an unknown tool, invalid JSON arguments (including an empty--args), an unreadable or invalid configuration file, invalid server settings (MCP_*), or a state-changing tool without--yes. A token the tool needs but that is not configured surfaces as a tool error (exit1). - A tool's own answer is not a failure. A tool that returns
falseor "not found" exits0; the runner reports what the tool returned. Invalid tool arguments are a tool error and exit1. - Redaction. String values under credential-named keys print as
<redacted>: keys ending intoken,auth,password,secret,credential,key,passwdorsession_id(a plural such astokensorapi_keyscounts), keys containingpassword,passwd,secret,credential,authorization,cookie,bearer,jwt,private_keyorbypass_code(sopassword_hash,Set-Cookieand a harvest task'scookiesare covered), andsessionid. String items in a list under such a key are hidden too. A harvest task's custom header (header,add-header,headers) is hidden when the header's name is credential-like by the same rules as keys (with-read as_), soAuthorization,Cookie,X-Api-Key,X-CSRF-Token,Private-Tokenand similar are hidden whileAccept,User-AgentandContent-Typeare not; session and authentication headers (X-SessionId,X-Authentication) count too, andpost-data(also spelledpost_dataorpostData) is hidden when it carries a field whose name containspassword,passwd,pwd,token,secret,authorizationorapi_key(such asclient_secretoruser[password]), or is a JSON body with such a key ("client_secret":,"access_token":); other header values stay visible. Any configured token value of 8 or more characters is also removed wherever it appears in a string. Structure is kept, so a health check still lists each token with its status. Descriptive fields such askey_name,token_type,key_idandauth_methodare not touched. Pass--revealto print everything as returned; it prints a warning on stderr before the call runs. Use it when you need a value that is itself a credential; the tools listed under New credentials require it. - Local files. The file tools read and write local paths only inside the directories named
by
MCP_FILE_ROOT, as in server mode. See Local File Access. - Logging. The log level defaults to WARNING, so stderr carries the
Target:line and any error; pass--log-levelto change it. The level also applies to the SDK's own log lines.
Argument gotchas¶
Every rule below is in the tool's schema and in --describe. They are listed here because each
one has caused a failed call.
| Tool | Argument | Rule |
|---|---|---|
a8_get_session_report |
user_id, username, org_id, org_name, hierarchy |
At most one; none reports on the token's own org. |
a8_get_session_report |
start_date, end_date |
MM-DD-YYYY (10-01-2026); ISO dates are refused. Returns aggregates only, never per-session rows. |
a8_extract_logs |
start_seq |
Required. 0, or min_seq from a8_get_extract_logs_info. |
a8_extract_logs, a8_stream_logs, a8_export_logs_csv |
start_date, end_date |
Integer days before today (90), not a date or epoch timestamp. end_date is midnight UTC, so 0 excludes today. |
a8_extract_logs |
limit |
1 to 1000. |
a8_extract_logs |
(paging) | While is_more is true, repeat the call with start_seq set to next_seq. |
a8_extract_logs |
log_types |
SESSION for egress and execution server; LOCATION_CHANGE is page navigation (URLs visited) and, like URL, POST_DATA and COOKIES, sensitive. No user filter: filter rows on username. |
| User/log tools vs org tools | org / org_name |
Same value (the API org name), different key. |
a8_create_context, a8_create_browsing_url |
username, org |
Exactly one; here org is the vanity URL slug. expires is a string, so quote an epoch. |
a8_create_harvest_task, a8_harvest_url |
urls |
A list holding exactly one URL. |
For the full walkthrough, see Run MCP Tools from a Shell.