Skip to content

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 .env file 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 (or https:// 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 for toolbox-standalone sessions; call a8_list_egresses with session_type="toolbox-standalone" to find the org's sovereign locations, or use egress_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 — Set true to 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 — Set true to retry each log type individually when the combined request fails; results are aggregated and any per-type errors appear in the type_errors field of the response (default: false). On a fallback response, next_seq is the lowest resume point among the types that still report more, so the next page can repeat rows — deduplicate by seq_id. Types in type_errors are not covered by next_seq; re-request them from the original start_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) or RuntimeError (API failures), each with an actionable message explaining what to check or try next.
  • Idempotency hints: a8_add_user and a8_create_org catch "already exists" responses and return the existing resource with _already_exists: true and a _hint field instead of raising an error. This allows agent workflows to proceed without explicit duplicate checks.
  • Rate limit retry: a8_extract_logs and log sequence tools automatically retry once on rate limit errors before surfacing the failure.
  • Lock contention retry: a8_extract_logs accepts retry_on_lock=true to automatically retry when the backend returns a concurrent-extraction lock error. The lock expires after 10 minutes; retry_delay (default 60s) and max_retries (default 3) are configurable.
  • Per-type fallback: a8_extract_logs accepts fallback_per_type=true to retry each log type individually when a combined request fails, aggregating partial results and reporting per-type errors in the type_errors field.
  • Input sanitization: Tools that accept org or task_id strings reject blank or whitespace-only values with a clear ValueError before 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 ConfigurationError when 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.yaml lists 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:

silo-sdk-mcp [OPTIONS]

Alternatively, invoke via the Python module:

python -m silo_sdk_mcp [OPTIONS]

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.yaml next to the installed silo_sdk_mcp package, 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-certfile and --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: {}); --call only
  • --yes - Confirm a tool that changes Silo state; --call only
  • --reveal - Print the result without redacting credentials; --call only
  • --log-level {DEBUG,INFO,WARNING,ERROR} - Logging level (default: INFO, or WARNING with --call or --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 TOOL prints 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 published inputSchema, 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-tools or the server options. It exits 0, or 2 for an unknown tool.
  • Argument names. A key in --args that the tool does not accept is refused (exit 2), 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_pin returns a newly generated temporary password, and a8_add_user and a8_bulk_add_users return each new user's bypass_code; redaction would hide the value after the change is already made. These tools are refused unless you pass both --yes and --reveal. So is a8_batch_request when its commands include a reset_pin or adduser command.
  • Exit codes. 0 success; 1 the tool failed; 2 a 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 (exit 1).
  • A tool's own answer is not a failure. A tool that returns false or "not found" exits 0; the runner reports what the tool returned. Invalid tool arguments are a tool error and exit 1.
  • Redaction. String values under credential-named keys print as <redacted>: keys ending in token, auth, password, secret, credential, key, passwd or session_id (a plural such as tokens or api_keys counts), keys containing password, passwd, secret, credential, authorization, cookie, bearer, jwt, private_key or bypass_code (so password_hash, Set-Cookie and a harvest task's cookies are covered), and sessionid. 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 _), so Authorization, Cookie, X-Api-Key, X-CSRF-Token, Private-Token and similar are hidden while Accept, User-Agent and Content-Type are not; session and authentication headers (X-SessionId, X-Authentication) count too, and post-data (also spelled post_data or postData) is hidden when it carries a field whose name contains password, passwd, pwd, token, secret, authorization or api_key (such as client_secret or user[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 as key_name, token_type, key_id and auth_method are not touched. Pass --reveal to 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-level to 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.