MCP Server Overview¶

The Authentic8 MCP Server exposes the entire Silo SDK as 73 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 — 73 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>68 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 (--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 73 tools organized by API category:

Browsing Isolation (6 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_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" or "tor"
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)
`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 or temp directory (saves as `harvest_<task_id>.zip` 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 (12 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_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 (22 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_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 all 26 valid log type strings
`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)

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
`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; 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: The HTTP endpoint should be deployed behind a reverse proxy with TLS termination in production.
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)
--list-tools - Print all registered tools and exit
--log-level {DEBUG,INFO,WARNING,ERROR} - Logging level (default: INFO)

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. Pass --host 127.0.0.1 (or publish only to loopback in Docker) and put a TLS-terminating reverse proxy in front of anything that needs to be reachable off the machine.

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.