Skip to content

Setup

This guide covers setting up the Authentic8 MCP server in both local (stdio) and remote (HTTP) modes.

Prerequisites

  • Python 3.11 or higher
  • Silo SDK (silo-sdk) installed
  • Valid Authentic8 API tokens

For remote (HTTP) deployment, you'll also need:

  • Docker and Docker Compose
  • A TLS certificate and private key for the server, or a reverse proxy that terminates TLS (nginx, Traefik, Caddy). See TLS (HTTPS).

Installation

Access required

The SDK source is distributed under access control. The release download below resolves only for accounts that have been granted access — if yours has not, it will return "not found" rather than a permission error. Contact your Authentic8 account team to request access.

# Download and extract the latest release
wget https://github.com/salesengr/silo-sdk-python/archive/refs/tags/v0.16.1.zip
unzip v0.16.1.zip
cd silo-sdk-python-0.16.1

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install with MCP support
pip install -e ".[mcp-server]"

From Git Clone

# Clone the repository
git clone https://github.com/salesengr/silo-sdk-python.git
cd silo-sdk-python

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install with MCP support
pip install -e ".[mcp-server]"

The [mcp-server] extra includes the MCP SDK, FastAPI, uvicorn, and all required dependencies.

From PyPI (Coming Soon)

No clone is needed. Install into a virtual environment of its own:

python3 -m venv silo-mcp-venv
source silo-mcp-venv/bin/activate  # Windows: silo-mcp-venv\Scripts\activate

pip install silo-sdk-mcp            # or: pip install "silo-sdk[mcp-server]"

Both commands install the same server. An install like this needs no config file — see Without a Clone for how it is configured.

Windows on ARM

On ARM64 Windows (Snapdragon laptops, or a Windows VM on Apple Silicon), two dependencies — cryptography and httptools — publish no prebuilt ARM64 Windows wheels, so pip tries to compile them and fails unless the Microsoft C++ Build Tools are installed. The simpler route is an x64 Python, which Windows runs under emulation and for which every dependency has a prebuilt wheel. Create the virtual environment with an x64 python.exe (C:\path\to\x64\python.exe -m venv silo-mcp-venv), or let uv fetch one: uv venv --seed --python cpython-3.13-windows-x86_64-none silo-mcp-venv. Windows on x64 is not affected.

Clone Repository

git clone https://github.com/salesengr/silo-sdk-python.git
cd silo-sdk-python

Build Docker Image

docker build -f Dockerfile.mcp -t a8-mcp-server .

Upgrading from 0.13.x

Version 0.14.0 renamed the Python package from silo_mcp to silo_sdk_mcp, so that it matches the silo-sdk distribution and the silo-sdk-mcp command. There is no compatibility shim. A plain git pull leaves an existing checkout in a broken state until you do two things.

1. Reinstall.

pip install -e ".[mcp-server]"

The silo-sdk-mcp console script and — for editable installs — the generated import finder both record the module path when you install, and neither updates on git pull. Until you reinstall, the console script fails with ModuleNotFoundError: No module named 'silo_mcp'.

python -m silo_sdk_mcp will appear to work before you reinstall

Run from the repository root, it picks the package up from the current directory rather than the installed one. That masks the problem — your MCP client invokes the console script, which is still broken. Reinstall rather than relying on it.

2. Move your credentials file (HTTP transports only).

mv silo_mcp/credentials.yaml silo_sdk_mcp/credentials.yaml
rmdir silo_mcp

credentials.yaml is deliberately untracked, so pulling removes the tracked files around it and leaves your file behind in an orphaned silo_mcp/ directory. Move it before starting Compose, and remove the leftover directory — it holds live API tokens.

A missed move fails confusingly, not loudly

Docker creates a bind mount's host path as an empty directory when it does not exist, rather than refusing to start. The container comes up and then dies trying to parse a directory as YAML.

Also update any MCP client configuration and any logging configuration:

Was Now
python -m silo_mcp python -m silo_sdk_mcp
from silo_mcp… import … from silo_sdk_mcp… import …
/app/silo_mcp/credentials.yaml /app/silo_sdk_mcp/credentials.yaml
Logger name silo_mcp Logger name silo_sdk_mcp

The logger rename is silent — downstream log filtering keyed on the old name simply stops matching, with no error.

Tool names are unchanged: every tool keeps its a8_ prefix.

Configuration

Configure Credentials

Create a .env file in the project root with your API tokens:

# Copy the example file
cp .env.example .env

# Edit .env with your actual tokens

Your .env should contain:

A8_ADMIN_TOKEN=your-admin-token-here
A8_SYNC_TOKEN=your-sync-token-here
A8_FILE_TOKEN=your-file-token-here
A8_LOG_TOKEN=your-log-token-here
A8_SCRAPE_TOKEN=your-scrape-token-here
A8_BUCKET_ID=your-bucket-id-here
A8_TOP_ORG=your-org-name-here        # top-level org name used in API calls
# A8_HARVEST_EGRESS_ORG=sub-org-name # org the harvest egress check uses (default: A8_TOP_ORG)

Warning

Never commit .env to version control. It's gitignored by default.

Without a Clone

An install from PyPI has no .env.example or config/ directory, and needs neither. When the working directory holds no config file, the server falls back to a copy of config/default.json bundled in the package, which reads every setting from an A8_* environment variable. Set the variables in your MCP client's env block — see Pattern 4.

Set the tokens for the tools you use; the server starts without the others. A tool whose token is missing fails when called, naming the variable to set:

Configuration error: Missing required configuration: SYNC_TOKEN (set A8_SYNC_TOKEN)

A config file in the launch directory takes precedence

The bundled copy is used only when the server's working directory contains no config/default.json, config.json or sample_config.json. If one is there, it replaces the bundled copy; a .env there overrides values from the env block. See Where load_config() finds its base configuration.

Test the Server

Verify the server starts and all tools are registered:

silo-sdk-mcp --list-tools

You should see output listing all 76 tools:

Authentic8 MCP Server - 76 tools
==================================================

Browsing Isolation (7 tools)
  a8_create_context
  a8_get_context
  ...

When to Use HTTP Mode

Choose an HTTP transport when:

  • Multiple users need to reach a server they do not run locally
  • You want centralized deployment behind a reverse proxy
  • You need monitoring and logging at the infrastructure level

For individual use, stdio mode is simpler.

Architecture

A server instance serves exactly one set of Authentic8 credentials. Multiple users are supported by running one instance per credential set and letting the proxy route each Bearer token to its own instance:

flowchart TD
    A["<b>Claude Code</b><br/>(User A)"]
    B["<b>Claude Desktop</b><br/>(User B)"]

    P["<b>Reverse Proxy</b><br/>nginx · Traefik · Caddy<br/><i>TLS termination · routes by Bearer token</i>"]

    MA["<b>MCP Server</b> — instance A<br/>Port 8080<br/>━━━━━━━━━━━━━━━━━━━━<br/><b>credentials.yaml</b><br/><code>client-key-A</code> → A8_ADMIN_TOKEN, …"]
    MB["<b>MCP Server</b> — instance B<br/>Port 8081<br/>━━━━━━━━━━━━━━━━━━━━<br/><b>credentials.yaml</b><br/><code>client-key-B</code> → A8_ADMIN_TOKEN, …"]

    A -->|"Bearer: client-key-A"| P
    B -->|"Bearer: client-key-B"| P
    P --> MA
    P --> MB

    style A fill:#e8f4fd,stroke:#1976d2,color:#0d1117
    style B fill:#e8f4fd,stroke:#1976d2,color:#0d1117
    style P fill:#f3e5f5,stroke:#7b1fa2,color:#0d1117
    style MA fill:#fff8e1,stroke:#f57c00,color:#0d1117
    style MB fill:#fff8e1,stroke:#f57c00,color:#0d1117

One Client Per Instance

A credentials file with more than one client will not start

The server refuses to start if credentials.yaml contains more than one entry under clients: — it logs the count and exits with status 1 rather than picking one and silently serving another client's tokens. Give each instance a credentials file holding exactly one client.

Bearer token validation is enforced on every request: a token that does not match that instance's client key is rejected with 401 Unauthorized before any tool runs.

For multiple clients, deploy one server instance per client behind a proxy (e.g., nginx, Traefik) that routes each Bearer token to its own process. See Scaling for the pattern.

Configure Credentials

Create silo_sdk_mcp/credentials.yaml with this instance's client credentials. The template ships inside the installed package, so copy it from there:

cp silo_sdk_mcp/credentials.yaml.example silo_sdk_mcp/credentials.yaml

Edit silo_sdk_mcp/credentials.yaml:

clients:
  "client-key-alice":
    ADMIN_TOKEN: "${ALICE_ADMIN_TOKEN}"
    SYNC_TOKEN: "${ALICE_SYNC_TOKEN}"
    FILE_TOKEN: "${ALICE_FILE_TOKEN}"
    LOG_TOKEN: "${ALICE_LOG_TOKEN}"
    SCRAPE_TOKEN: "${ALICE_SCRAPE_TOKEN}"
    BUCKET_ID: "${ALICE_BUCKET_ID}"
    API_URL: "https://extapi.authentic8.com"

A second client belongs in a second file, served by a second instance — not as a second entry here.

Client keys are arbitrary strings you generate. Clients provide them via Authorization: Bearer <key>.

Environment variables are substituted at runtime using ${VAR} or ${VAR:-default} syntax.

Diagnostic, cache and session-default keys need no entry here. This transport builds its configuration from credentials.yaml alone — it never reads config/default.json — so these four fall back to the environment, with the same defaults the shipped config file uses:

Config key Environment variable Default
ENABLE_REQUEST_LOGGING A8_ENABLE_REQUEST_LOGGING false
ENABLE_STATUS_CACHE A8_ENABLE_STATUS_CACHE false
STATUS_CACHE_TTL A8_STATUS_CACHE_TTL 30
DEFAULT_MAX_USES A8_DEFAULT_MAX_USES 1

Add a line for one only to pin it for this client whatever the environment says.

Warning

Never commit credentials.yaml with real tokens. It's gitignored by default.

Set Environment Variables

Create a .env.http file for the HTTP transport's environment variables:

# Alice's credentials — this instance's client
ALICE_ADMIN_TOKEN=actual-token-here
ALICE_SYNC_TOKEN=actual-token-here
ALICE_FILE_TOKEN=actual-token-here
ALICE_LOG_TOKEN=actual-token-here
ALICE_SCRAPE_TOKEN=actual-token-here
ALICE_BUCKET_ID=actual-bucket-id

Note

Add .env.http to .gitignore if using a custom name.

How Credentials Flow into the Container

The container has no .env file

The Docker image does not include your .env.http or any credential file — they are gitignored and never copied into the build context.

Credentials reach the container in two steps:

  1. credentials.yaml is volume-mounted into the container (read-only). It maps each client Bearer token to a set of ${VAR} references.
  2. The actual token values are injected as environment variables via --env-file or env_file: in Docker Compose. The MCP server resolves ${VAR} references in credentials.yaml against the container's environment at startup.

Without both steps, the server starts but ${VAR} placeholders remain unresolved and API calls will fail with authentication errors.

Local File Access

Four tools touch the host filesystem, and all four are confined to the directories named by MCP_FILE_ROOT. This applies to every transport.

Tool Filesystem access
a8_upload_file Reads a local file
a8_download_file Writes a local file
a8_download_harvest_result Writes the harvest output ZIP
a8_export_logs_csv Writes the CSV, and removes it if the export fails partway

The last two also generate a default path when output_path is omitted, and that default lands inside the first root rather than in the system temporary directory.

# A single root
export MCP_FILE_ROOT=/srv/silo-mcp/files

# Or a PATH-style list — a read directory and a write directory
export MCP_FILE_ROOT=/srv/silo-mcp/inbox:/srv/silo-mcp/outbox

The list separator is the platform's PATH separator: : on macOS and Linux, ; on Windows.

$env:MCP_FILE_ROOT = "C:\silo-mcp\inbox;C:\silo-mcp\outbox"
Behavior Detail
Default A silo_sdk_mcp_files directory under the system temporary directory, created on demand
Missing directory Created at startup of the first file operation; a path that exists but is not a directory is an error
Relative paths Anchored to the first root, not to the server's working directory
Symlinks Resolved before the check, so a link inside a root cannot point outside one
Violation The tool returns an error naming the permitted roots; nothing is read or written

This is a security boundary, not a convenience default

An upload reads a local file and sends its contents to the storage API, and the path is chosen by a model that routinely reads untrusted web content — the very content this SDK exists to fetch. Text on a fetched page can talk a model into naming a path the operator never intended. The write side is worse still for a8_download_harvest_result, where both halves are model-chosen: the destination path and the bytes, which are a harvest of a URL the model also picked. Point MCP_FILE_ROOT at the narrowest directory your workflow actually needs, and do not set it to a home directory, a repository root, or /.

Upgrading from 0.13.x

Earlier releases placed no restriction on these paths. If a workflow moves files through a specific directory, set MCP_FILE_ROOT to it before upgrading, or those calls will start failing.

Upgrading from 0.14.1

a8_download_harvest_result and a8_export_logs_csv were not covered by MCP_FILE_ROOT before 0.14.2. An absolute output_path outside the root now raises instead of writing, and their generated defaults moved out of the system temporary directory and into the root.

Long-Running Tool Concurrency

Two tools block for a wait the caller chooses: a8_wait_for_harvest_task (timeout_seconds, default 300) and a8_harvest_url (max_wait_seconds, default 1800). The server runs them on a thread pool of their own, separate from the pool every other tool uses, so concurrent long waits cannot hold up quick calls such as user or org lookups.

MCP_LONG_WAIT_WORKERS sets how many of those waits can run at once. It applies to every transport, and the limit is per server process: over HTTP, every session connected to the same server shares it.

export MCP_LONG_WAIT_WORKERS=16
Behavior Detail
Default 8
Pool full Further long-wait calls queue until a running one finishes; other tools are unaffected
Cancelled while queued The call never starts
Invalid value Anything but a positive integer stops the server at startup

A worker is held for the whole wait

A client cancelling a wait that has already started frees its own request, but the server finishes polling before the worker is released. Raise MCP_LONG_WAIT_WORKERS if your workflow runs more simultaneous harvest waits than the default allows.

Maximum wait

MCP_MAX_WAIT_SECONDS caps how long a single wait can be, so a full long-wait pool frees up within a known time. Both tools reject a longer wait before doing anything: a8_harvest_url checks it before it creates the harvest task.

export MCP_MAX_WAIT_SECONDS=3600
Behavior Detail
Default 1800 (30 minutes), the same as a8_harvest_url's default wait
Wait above the cap Rejected with an error naming the cap; nothing is created or polled
Polling interval longer than the wait Rejected
Invalid value Anything but a positive integer stops the server at startup

A wait that times out does not cancel the harvest task. To wait longer than the cap, call a8_wait_for_harvest_task again with the same task ID.

Egress validation

Before a8_create_context, a8_create_research_session and a8_create_browsing_url create a context for a username, the server checks the requested egress against that user's live directory (a8_list_egresses). An egress the platform does not offer is rejected with an error listing what is offered, instead of a context that fails at launch. An org's Launcher Options can hide a region from that directory, so the model can retry with allow_unlisted_egress=true to create the context anyway.

a8_create_harvest_task and a8_harvest_url check the egress against the pool the task type draws from — the asset pool for asset and wget, the browsing pool for the rest — for HARVEST_EGRESS_ORG, or TOP_ORG if unset. An unlisted egress is refused with what the pool offers. Because an org's Launcher Options hide regions from that list but not from harvest, the model can retry with allow_unlisted_egress=true.

export MCP_EGRESS_VALIDATION=offline   # default: live
Behavior Detail
Default live
No username (org only) Not checked live — an org's directory does not cover its users
Empty directory Not refused — the platform chooses the egress
Directory lookup fails Not refused — logged, and the built-in checks apply
Browsing, egress not offered Refused; retry with allow_unlisted_egress=true to create the context anyway
Harvest, unlisted egress Refused; retry with allow_unlisted_egress=true to send it anyway
Harvest, no A8_ADMIN_TOKEN, or neither A8_HARVEST_EGRESS_ORG nor A8_TOP_ORG Not checked — the harvest check needs a token and an org; logged, and the task is created
Harvest, empty pool Not refused — an org lookup sees only egress provisioned to that org and the orgs above it; set A8_HARVEST_EGRESS_ORG to the sub-org the harvest token belongs to
offline Only the built-in, advisory checks
Invalid value Anything but live or offline stops the server at startup

Client Configuration

Claude Desktop

Pattern 1: CLI Entry Point (Recommended)

After installing with pip install -e ".[mcp-server]", the silo-sdk-mcp command is available directly in the virtual environment. The SDK loads .env automatically via python-dotenv, so no wrapper script is needed.

Ensure .env exists:

cp .env.example .env
# Edit .env with your actual API tokens

macOS/Linux:

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "silo-sdk-mcp": {
      "command": "/absolute/path/to/silo-sdk-python/.venv/bin/silo-sdk-mcp",
      "args": [],
      "cwd": "/absolute/path/to/silo-sdk-python"
    }
  }
}

Windows:

Add to %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "silo-sdk-mcp": {
      "command": "C:\\absolute\\path\\to\\silo-sdk-python\\.venv\\Scripts\\silo-sdk-mcp.exe",
      "args": [],
      "cwd": "C:\\absolute\\path\\to\\silo-sdk-python"
    }
  }
}

Tip

Use absolute paths for the command and cwd fields. Relative paths and environment variables like $HOME or ~ don't expand reliably in posix_spawn.

Restart Claude Desktop after editing the config file.

Pattern 2: Direct Python

This pattern invokes Python directly. It requires passing tokens via the env section.

Warning

Environment variable expansion in the env section is client-dependent and may not work reliably in all MCP clients. Use Pattern 1 instead.

{
  "mcpServers": {
    "silo-sdk-mcp": {
      "command": "/absolute/path/to/silo-sdk-python/.venv/bin/python",
      "args": ["-m", "silo_sdk_mcp", "--transport", "stdio"],
      "cwd": "/absolute/path/to/silo-sdk-python",
      "env": {
        "A8_ADMIN_TOKEN": "your-actual-token-here",
        "A8_SYNC_TOKEN": "your-actual-token-here",
        "A8_FILE_TOKEN": "your-actual-token-here",
        "A8_LOG_TOKEN": "your-actual-token-here",
        "A8_SCRAPE_TOKEN": "your-actual-token-here",
        "A8_BUCKET_ID": "your-actual-bucket-id-here"
      }
    }
  }
}

Pattern 3: Docker stdio

Run the MCP server in a Docker container. Claude spawns the container as a subprocess and communicates via stdin/stdout, identical to the non-Docker patterns.

Build the Docker image first:

cd /path/to/silo-sdk-python
docker build -f Dockerfile.mcp -t a8-mcp-server .

How the container gets credentials

The Docker image does not include your .env file — it is gitignored and never copied into the build context. The container reads config/default.json (which contains ${A8_ADMIN_TOKEN} placeholders) and resolves them from the process environment. You must supply real token values via one of the three methods below.

Method A: --env-file (recommended)

Pass your .env file directly to Docker. Docker reads it as plain KEY=value pairs and injects them as environment variables into the container:

{
  "mcpServers": {
    "silo-sdk-mcp": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--env-file", "/absolute/path/to/silo-sdk-python/.env",
        "a8-mcp-server"
      ]
    }
  }
}

Note

Docker's --env-file reads plain KEY=value pairs only — it does not expand shell variables like ${OTHER_VAR} within the file. If your .env contains any variable references, use Method C (volume mount) instead.

Method B: Explicit -e flags

Inline each token directly in the args list. Useful when tokens come from a secrets manager or CI environment rather than a file:

{
  "mcpServers": {
    "silo-sdk-mcp": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "A8_ADMIN_TOKEN=your-admin-token",
        "-e", "A8_SYNC_TOKEN=your-sync-token",
        "-e", "A8_FILE_TOKEN=your-file-token",
        "-e", "A8_LOG_TOKEN=your-log-token",
        "-e", "A8_SCRAPE_TOKEN=your-scrape-token",
        "-e", "A8_BUCKET_ID=your-bucket-id",
        "-e", "A8_TOP_ORG=your-org-name",
        "a8-mcp-server"
      ]
    }
  }
}

Method C: Volume-mount the .env file

Mount your .env into the container at /app/.env. The SDK's config loader uses python-dotenv to load this file at startup, which does support variable interpolation:

{
  "mcpServers": {
    "silo-sdk-mcp": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "/absolute/path/to/silo-sdk-python/.env:/app/.env:ro",
        "a8-mcp-server"
      ]
    }
  }
}

This is the closest equivalent to running the server natively with a .env file and is recommended if your .env uses variable references.

Pattern 4: Installed Package, No Clone

For a server installed with pip install silo-sdk-mcp (see From PyPI). Point command at the silo-sdk-mcp in that virtual environment and put the tokens in the env block. No cwd is needed: with no config file in the launch directory, the server reads its configuration from these variables alone.

macOS/Linux:

{
  "mcpServers": {
    "silo-sdk-mcp": {
      "command": "/absolute/path/to/silo-mcp-venv/bin/silo-sdk-mcp",
      "args": [],
      "env": {
        "A8_ADMIN_TOKEN": "your-admin-token",
        "A8_SYNC_TOKEN": "your-sync-token",
        "A8_FILE_TOKEN": "your-file-token",
        "A8_LOG_TOKEN": "your-log-token",
        "A8_SCRAPE_TOKEN": "your-scrape-token",
        "A8_BUCKET_ID": "your-bucket-id",
        "A8_TOP_ORG": "your-org-name"
      }
    }
  }
}

Windows:

{
  "mcpServers": {
    "silo-sdk-mcp": {
      "command": "C:\\absolute\\path\\to\\silo-mcp-venv\\Scripts\\silo-sdk-mcp.exe",
      "args": [],
      "env": {
        "A8_ADMIN_TOKEN": "your-admin-token",
        "A8_TOP_ORG": "your-org-name"
      }
    }
  }
}

Omit the variables for APIs you do not use — see Without a Clone.

Use literal values, not ${...} references

Write the actual token values into the env block. Whether a client expands ${VAR} there is client-dependent, as noted under Pattern 2, and an unexpanded reference reaches the server as a literal string that the API rejects.

The client config file now holds live tokens

Keep it out of version control and readable only by your user account.

Claude Code

The Claude Code CLI manages MCP servers via claude mcp add, not via mcpServers in settings.json (that field is for Claude Desktop only). Point it at the silo-sdk-mcp in your virtual environment and pass the tokens with -e, one flag per variable, as in Pattern 4.

Installed Package, No Clone

For a server installed from PyPI:

claude mcp add silo-sdk-mcp --scope user \
  -e A8_ADMIN_TOKEN=your-admin-token \
  -e A8_SYNC_TOKEN=your-sync-token \
  -e A8_FILE_TOKEN=your-file-token \
  -e A8_LOG_TOKEN=your-log-token \
  -e A8_SCRAPE_TOKEN=your-scrape-token \
  -e A8_BUCKET_ID=your-bucket-id \
  -e A8_TOP_ORG=your-org-name \
  -- /absolute/path/to/silo-mcp-venv/bin/silo-sdk-mcp

On Windows, point at silo-sdk-mcp.exe under the venv's Scripts directory instead. PowerShell continues lines with a backtick rather than \, and the -- separator must be quoted:

claude mcp add silo-sdk-mcp --scope user `
  -e A8_ADMIN_TOKEN=your-admin-token `
  -e A8_TOP_ORG=your-org-name `
  '--' C:\absolute\path\to\silo-mcp-venv\Scripts\silo-sdk-mcp.exe

When Claude Code is installed with npm, claude in PowerShell runs a claude.ps1 script, and PowerShell consumes an unquoted -- itself instead of passing it on. The command then fails with error: missing required argument 'commandOrUrl'. Quoting it as '--' passes it through, and is harmless when claude is the native claude.exe.

Omit the variables for APIs you do not use — see Without a Clone.

From a Clone

Use the same command, pointed at the clone's virtual environment:

claude mcp add silo-sdk-mcp --scope user \
  -e A8_ADMIN_TOKEN=your-admin-token \
  -e A8_TOP_ORG=your-org-name \
  -- /absolute/path/to/silo-sdk-python/.venv/bin/silo-sdk-mcp

A .env in the clone is read only from inside the clone

The server reads .env, .env.{A8_CONFIG_ENV} and config/ from its working directory, not from the clone it was installed from. Claude Code's MCP server configuration has no working-directory (cwd) setting, so unlike Pattern 1 for Claude Desktop, the server starts in whatever directory you started Claude Code from. Pass the tokens with -e, as above; with no config file in that directory, the server reads its configuration from those variables alone. A session started inside the clone is the exception: there the clone's config/default.json and .env are loaded, and a value in .env overrides the same variable passed with -e.

Choosing a scope

--scope user makes the server available in every project. The default, --scope local, limits it to the directory you ran claude mcp add in. Both store the entry, tokens included, in ~/.claude.json. Avoid --scope project here: it writes the entry to a .mcp.json file in the project root, which is meant to be shared and would carry your tokens with it.

Verify the server is connected:

claude mcp list
# silo-sdk-mcp: /absolute/path/to/silo-mcp-venv/bin/silo-sdk-mcp  - ✔ Connected

Note

To remove the user-scope entry, run claude mcp remove silo-sdk-mcp --scope user.

Start the Server

With Docker Compose

The provided docker-compose.mcp.yml defines an mcp-http service. Add env_file: to inject the token values that credentials.yaml references:

services:
  mcp-http:
    build:
      context: .
      dockerfile: Dockerfile.mcp
    volumes:
      # Step 1: mount the credentials map (client keys → ${VAR} references)
      - ./silo_sdk_mcp/credentials.yaml:/app/silo_sdk_mcp/credentials.yaml:ro
    ports:
      # Bind loopback explicitly. A bare "8080:8080" binds 0.0.0.0 and
      # exposes the server to the whole network.
      - "127.0.0.1:8080:8080"
    env_file:
      # Step 2: inject the actual token values that credentials.yaml references
      - .env.http
    environment:
      # Required because the server binds 0.0.0.0 inside the container:
      # without it the server refuses to start, whatever port is published.
      # List the host:port your client actually sends.
      - MCP_ALLOWED_HOSTS=127.0.0.1:8080,localhost:8080
    command: >
      silo-sdk-mcp --transport streamable-http
      --host 0.0.0.0 --port 8080
      --credentials /app/silo_sdk_mcp/credentials.yaml

The shipped docker-compose.mcp.yml derives MCP_ALLOWED_HOSTS and the published address from MCP_BIND_HOST (default 127.0.0.1), so setting MCP_BIND_HOST or MCP_ALLOWED_HOSTS in the shell overrides them.

sse is the legacy transport

--transport sse is still accepted and serves at /sse rather than /mcp. It stays available for older clients, but Streamable HTTP supersedes it and is what the shipped Compose file uses. New deployments should use streamable-http.

The mount path must match the package path

The container's default credentials path sits next to the installed package, at /app/silo_sdk_mcp/credentials.yaml. Mount the file there — mounting it at /app/credentials.yaml leaves the default pointing at a file that does not exist.

Start the server:

docker compose -f docker-compose.mcp.yml up -d mcp-http

View logs:

docker compose -f docker-compose.mcp.yml logs -f mcp-http

Stop the server:

docker compose -f docker-compose.mcp.yml down

Manual Docker Run

Without Docker Compose — both steps in one command:

docker run -d \
  --name silo-sdk-mcp-http \
  -p 127.0.0.1:8080:8080 \
  -v $(pwd)/silo_sdk_mcp/credentials.yaml:/app/silo_sdk_mcp/credentials.yaml:ro \
  --env-file .env.http \
  -e MCP_ALLOWED_HOSTS=127.0.0.1:8080,localhost:8080 \
  a8-mcp-server \
  silo-sdk-mcp --transport streamable-http \
    --host 0.0.0.0 --port 8080 \
    --credentials /app/silo_sdk_mcp/credentials.yaml

The -v flag mounts the credential map; --env-file injects the token values it references.

TLS (HTTPS)

Without TLS the server speaks plain HTTP, and every request carries its Bearer token in the clear. For anything beyond loopback, either serve HTTPS from the server itself, as described here, or put it behind a reverse proxy that terminates TLS (see Reverse Proxy Configuration). Use a proxy when you want automatic certificates (ACME) or one public name in front of several server instances.

Give the server a certificate and its private key. A non-loopback --host such as 0.0.0.0 makes the server refuse to start unless MCP_ALLOWED_HOSTS lists the host:port values clients will use:

MCP_ALLOWED_HOSTS=localhost:8080,192.0.2.10:8080 \
silo-sdk-mcp --transport streamable-http --host 0.0.0.0 --port 8080 \
  --ssl-certfile /certs/tls.crt --ssl-keyfile /certs/tls.key
Flag Environment variable Value
--ssl-certfile MCP_TLS_CERTFILE PEM server certificate, optionally followed by its chain
--ssl-keyfile MCP_TLS_KEYFILE PEM private key for that certificate
--ssl-client-ca MCP_TLS_CLIENT_CA PEM CA bundle; when set, clients must present a certificate it signed

A flag wins over its environment variable, and a blank variable counts as unset. An empty flag value is rejected. The variables are read from the server's process environment only, not from a .env file. With neither certificate nor key set, the server serves plain HTTP. The startup log names the scheme (https://… or http://…). The options apply to the HTTP transports only: with --transport stdio the flags make the server exit with an error, and the variables are ignored.

The server checks the files before it starts and exits with a one-line error if only one of certificate and key is set, a client CA is set without a certificate and key, a path is missing or is a directory, a file cannot be read, the key does not match the certificate, the key is passphrase-protected, or the client CA is not a PEM file. Passphrase-protected keys are not supported, so store the key unencrypted and restrict who can read the file instead. Connections use TLS 1.2 or later, and TLS 1.2 connections use forward-secret AEAD cipher suites only.

With Docker Compose, layer docker-compose.mcp-tls.yml over the base file (the base service also needs the env_file: added under With Docker Compose above) and point MCP_TLS_DIR at the absolute path of a directory holding tls.crt and tls.key. Keep that directory outside the repository: the image is built from the repository, and keys must never sit in the build context, even though .dockerignore excludes key files.

MCP_TLS_DIR="$HOME/silo-mcp-certs" docker compose \
  -f docker-compose.mcp.yml -f docker-compose.mcp-tls.yml up -d mcp-http

The directory is mounted read-only at /app/tls. The container runs as uid 1000, so the certificate, the key and (for mutual TLS) the client CA must all be readable by that user. On Linux, give group 1000 read access rather than handing it ownership of the private key; the directory must also be traversable by that group:

sudo chgrp 1000 "$HOME/silo-mcp-certs" "$HOME/silo-mcp-certs/"*
chmod 750 "$HOME/silo-mcp-certs"
chmod 640 "$HOME/silo-mcp-certs/"*

If the files are not readable, the container exits with Refusing to start: Cannot load TLS certificate … and a Permission denied error.

Compose refuses to start when MCP_TLS_DIR is unset or empty. A path that does not exist is created by Docker as an empty directory, and the server then exits with Refusing to start: TLS certificate path is a directory, not a file.

The base file publishes the port on 127.0.0.1 and allows only 127.0.0.1:8080 and localhost:8080 as Host values. To serve other machines, set MCP_BIND_HOST to the address to publish on, and set MCP_ALLOWED_HOSTS to every host:port clients will send. Compose reads both from the shell environment or the Compose .env file, and the name in the client URL must also be in the certificate.

Rotating certificates

The server reads the files once at startup. Replace them, then restart the server or container.

Requiring client certificates (mutual TLS)

Add a client CA, and every connection must present a certificate signed by it before the Bearer token is checked. A stolen token is then useless without a client certificate as well.

There is no revocation checking (no CRL or OCSP), so a client certificate stays valid until it expires. To cut off one client, issue client certificates from a new client CA, replace the CA file, and restart the server.

MCP_ALLOWED_HOSTS=localhost:8080,192.0.2.10:8080 \
silo-sdk-mcp --transport streamable-http --host 0.0.0.0 --port 8080 \
  --ssl-certfile /certs/tls.crt --ssl-keyfile /certs/tls.key \
  --ssl-client-ca /certs/client-ca.pem

With Compose, put the CA file in MCP_TLS_DIR and set MCP_TLS_CLIENT_CA=/app/tls/client-ca.pem, the path inside the container. Compose reads it from the shell environment or the Compose .env file:

MCP_TLS_DIR="$HOME/silo-mcp-certs" MCP_TLS_CLIENT_CA=/app/tls/client-ca.pem \
  docker compose -f docker-compose.mcp.yml -f docker-compose.mcp-tls.yml up -d mcp-http

This guide verifies mutual TLS with curl (--cert and --key) and does not show a client configuration for presenting a client certificate. Check your MCP client's documentation for client-certificate support before turning this on.

A certificate for testing

For a workstation or a local VM, mkcert creates a local CA and a certificate signed by it. Include every name and IP address clients will use. A client connecting by IP address needs that IP in the certificate:

mkcert -install
mkdir -p "$HOME/silo-mcp-certs"
mkcert -cert-file "$HOME/silo-mcp-certs/tls.crt" -key-file "$HOME/silo-mcp-certs/tls.key" \
  localhost 127.0.0.1 192.0.2.10

Generate the files outside the repository, for the reason given under Docker Compose above.

Making the client trust the certificate

A certificate from a public CA needs nothing extra. For a private CA, such as mkcert's or your organization's, the client has to trust it. Node.js-based clients typically use their own bundled CA list rather than the operating system's. NODE_EXTRA_CA_CERTS adds a CA for them, and Claude Code documents this variable for trusting a custom CA. For other clients, check their documentation. Point the variable at the CA certificate in the environment that starts the client:

export NODE_EXTRA_CA_CERTS="$(mkcert -CAROOT)/rootCA.pem"

Then use the https:// URL in the client configuration below. With direct TLS (no proxy) the URL includes the port, for example https://<name>:8080/mcp; the examples below show the proxy form. The host name in the client URL must be one the certificate covers, and any name you connect to must also be listed in MCP_ALLOWED_HOSTS when the server binds a non-loopback address.

Reverse Proxy Configuration

The endpoint path depends on the transport: streamable-http serves at /mcp, the legacy sse transport at /sse. A reverse proxy is the alternative to the server's own TLS: it terminates TLS and forwards plain HTTP to the server, so keep that hop on loopback or a private network. If the server's own TLS is also enabled, the proxy's upstream must be https:// and the proxy must trust the server's CA. If the server requires client certificates, the proxy must present one too.

Set MCP_ALLOWED_HOSTS to the public name

Behind a proxy the server sees the Host header the client sent — mcp.yourcompany.com, not localhost. If that name is not in MCP_ALLOWED_HOSTS, DNS-rebinding protection rejects every request. Set MCP_ALLOWED_HOSTS=mcp.yourcompany.com:443 (or whatever your clients send) alongside the proxy config below.

nginx Example:

server {
    listen 443 ssl http2;
    server_name mcp.yourcompany.com;

    ssl_certificate /etc/ssl/certs/mcp.yourcompany.com.crt;
    ssl_certificate_key /etc/ssl/private/mcp.yourcompany.com.key;

    location /mcp {
        proxy_pass http://localhost:8080/mcp;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Streaming responses: don't let the proxy buffer them
        proxy_set_header Connection '';
        proxy_buffering off;
        proxy_cache off;
        chunked_transfer_encoding off;
    }
}

Traefik Example:

http:
  routers:
    mcp-http:
      rule: "Host(`mcp.yourcompany.com`) && Path(`/mcp`)"
      service: mcp-http-service
      tls:
        certResolver: letsencrypt

  services:
    mcp-http-service:
      loadBalancer:
        servers:
          - url: "http://localhost:8080"

Client Configuration

Clients connect to the server's /mcp endpoint with their Bearer token. A client still on the legacy sse transport connects to /sse instead.

Claude Desktop:

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "silo-sdk-mcp": {
      "url": "https://mcp.yourcompany.com/mcp",
      "headers": {
        "Authorization": "Bearer client-key-alice"
      }
    }
  }
}

Claude Code:

Add to project .mcp.json:

{
  "mcpServers": {
    "silo-sdk-mcp": {
      "url": "https://mcp.yourcompany.com/mcp",
      "headers": {
        "Authorization": "Bearer client-key-alice"
      }
    }
  }
}

Cursor / Other Clients:

Most MCP clients support Streamable HTTP with a similar config structure. Clients that only speak the legacy SSE transport work too — point them at /sse and start the server with --transport sse. Consult the client's MCP documentation.

Security Considerations

Authentication:

  • Bearer tokens act as API keys. Generate long, random strings (e.g., openssl rand -hex 32)
  • Rotate tokens periodically and when team members leave
  • Use HTTPS for all client-server communication (never plain HTTP in production)
  • Consider mutual TLS (see Requiring client certificates) so a stolen Bearer token is useless without a client certificate
  • Protect the TLS private key: it is stored unencrypted, so restrict read access to the account that runs the server

Credential Isolation:

  • Invalid Bearer tokens result in 401 Unauthorized
  • Note: An instance serves exactly one client's API credentials, and refuses to start if given a credentials file listing more than one. Isolating clients from each other means one instance per client. See One Client Per Instance above.

Network Security:

  • Serve HTTPS from the server (see TLS (HTTPS)), or deploy behind a reverse proxy with TLS termination; in the proxy case keep the proxy-to-server hop on loopback or a private network
  • Use a firewall to restrict access to port 8080 (to the proxy when you use one, otherwise to your clients' networks)
  • Enable rate limiting at the reverse proxy layer to prevent abuse
  • Consider IP allowlisting if clients connect from known networks

Monitoring:

  • Log all requests with client identifiers (but redact sensitive data)
  • Monitor for failed auth attempts—may indicate credential compromise
  • Set up alerts for unusual API usage patterns

Health Checks

The MCP server doesn't expose a dedicated health endpoint. Monitor with Docker health checks:

services:
  mcp-http:
    healthcheck:
      test: ["CMD", "python", "-c", "import socket; s = socket.socket(); s.connect(('localhost', 8080)); s.close()"]
      interval: 30s
      timeout: 5s
      retries: 3

Or use a simple TCP check from your monitoring system.

Scaling

For high-traffic deployments:

  • Horizontal scaling: Run multiple MCP server containers behind a load balancer
  • Sticky sessions: Not required—each request is independent
  • Shared credentials: Use a secrets manager (AWS Secrets Manager, HashiCorp Vault) instead of credentials.yaml

Verify Connection

After configuring your client:

  1. Restart the application (Claude Desktop, Claude Code, etc.)
  2. Check the MCP connection status (usually shown in settings or status bar)
  3. Test by asking Claude: "List users in [your org name] organization"

If the MCP server is connected, you'll see all tools loaded. If there's an error, check:

  • The client's MCP logs, which capture the server's startup errors:
    • Claude Desktop: mcp*.log files in ~/Library/Logs/Claude/ (macOS) or %APPDATA%\Claude\logs\ (Windows)
    • Claude Code: run /mcp in a session to see each server's status, or start Claude Code with claude --debug for verbose MCP output
    • Other clients: see the client's documentation for its log location
  • Verify the client's env block (or Claude Code's -e flags) sets the required tokens, or — for a client launched with its working directory set to a clone, such as Pattern 1 — that the clone's .env contains them
  • Ensure absolute paths in config (no $HOME, ~, or relative paths)
  • Verify the silo-sdk-mcp binary exists in the venv: ls .venv/bin/silo-sdk-mcp (stdio mode)
  • Review server logs for authentication errors (HTTP mode)

Troubleshooting

ModuleNotFoundError: No module named 'silo_mcp'

Symptom: silo-sdk-mcp exits immediately with ModuleNotFoundError: No module named 'silo_mcp', usually right after upgrading.

Cause: The package was renamed to silo_sdk_mcp in 0.14.0, but the console script and the editable-install import finder still point at the old path. Both are generated at install time and do not update on git pull.

Fix: Reinstall — see Upgrading from 0.13.x.

pip install -e ".[mcp-server]"

MCP Server Fails to Start (stdio mode)

Symptom: Connection error in Claude Desktop/Code

Check:

# Verify Python path is correct
/absolute/path/to/silo-sdk-python/.venv/bin/python --version

# Test server manually
cd /path/to/silo-sdk-python
source .venv/bin/activate
silo-sdk-mcp --list-tools

Missing required configuration (stdio mode)

Symptom: The server starts, but a tool fails with Configuration error: Missing required configuration: SYNC_TOKEN (set A8_SYNC_TOKEN).

Cause: The token that tool's API needs is not set. The server does not check tokens at startup, so it runs with only some of them and reports a missing one when a tool needs it.

Fix: Set the variable the message names — in .env for a clone, or in the client's env block for an installed package — and restart the client.

Values in the env Block Are Ignored (stdio mode)

Symptom: An installed-package setup (Pattern 4) behaves as if the env block values were different or missing.

Cause: The server's working directory contains a config/default.json, config.json, sample_config.json or .env. Any of these takes precedence over the bundled configuration, and a .env overrides variables the client sets.

Fix: Remove or rename the file, or set the client's cwd to a directory that holds none of them. Claude Code has no cwd setting — its server starts in the directory the session was started from, so start the session somewhere else. See Where load_config() finds its base configuration.

Client Connection Refused (HTTP mode)

Symptom: Clients cannot connect to the server endpoint (/mcp, or /sse on the legacy transport)

Check:

  • Server is running: docker ps | grep silo-sdk-mcp-http
  • Port 8080 is accessible: curl http://localhost:8080/mcp (with TLS enabled use https://, adding --cacert <ca file> for a private CA; with mutual TLS on, curl also needs --cert <client cert> --key <client key>)
  • The URL scheme matches the server: http:// against a TLS server fails with an empty reply or a connection reset, and the server logs no HTTP request
  • Reverse proxy configuration is correct
  • Firewall allows traffic to reverse proxy

CryptError or API Authentication Failures

Symptom: CryptError: Invalid data or 401 Unauthorized

Cause: Environment variables not loaded correctly (stdio) or ${VAR} references in credentials.yaml were not resolved (HTTP)

Fix (stdio): Use Pattern 1 (CLI entry point) instead of Pattern 2

Fix (HTTP):

  • Confirm --env-file .env.http (manual run) or env_file: .env.http (Compose) is present
  • Check that variable names in .env.http match exactly what silo_sdk_mcp/credentials.yaml references (e.g., ALICE_ADMIN_TOKEN in .env.http must match ${ALICE_ADMIN_TOKEN} in the YAML)
  • Ensure ${VAR} syntax is used in the YAML — not $VAR or {VAR}
  • Review server startup logs for credential loading warnings:
    docker compose -f docker-compose.mcp.yml logs mcp-http | grep -i credential
    

401 Unauthorized (HTTP mode)

Symptom: Client gets 401 Unauthorized when connecting

Cause: Bearer token not found in credentials.yaml or missing Authorization header

Fix:

  • Verify client Bearer token matches a key in credentials.yaml
  • Check client config has Authorization: Bearer <token> header
  • Review server logs for authentication errors

Certificate Errors (HTTP mode)

Symptom: The server exits at startup with Refusing to start: … naming a TLS setting, or clients fail with a certificate verification error.

Fix (server): The message names the file and the problem. Check that both --ssl-certfile and --ssl-keyfile (or MCP_TLS_CERTFILE and MCP_TLS_KEYFILE) are set, that the paths are files rather than directories (a Compose MCP_TLS_DIR that does not exist becomes an empty directory), that the key belongs to the certificate and is not passphrase-protected, and that the user running the server can read the files (uid 1000 in the container).

Fix (client):

  • self-signed certificate or unable to verify the first certificate: the client does not trust the CA. Set NODE_EXTRA_CA_CERTS for Node.js clients (see Making the client trust the certificate), or add the missing intermediate certificates to the end of tls.crt.
  • Hostname/IP does not match certificate: the name or IP in the client URL is not in the certificate. Reissue it with that name.
  • The client fails with a TLS alert (such as certificate required or bad certificate) or a connection reset, and the server logs no HTTP request: client certificates are required (--ssl-client-ca) and the client sent none, or sent one from a different CA.

Server Crashes (HTTP mode)

Symptom: Container exits immediately after start

Check logs:

docker compose -f docker-compose.mcp.yml logs mcp-http

Common causes:

  • credentials.yaml file not found or invalid YAML syntax
  • Missing required environment variables
  • Port 8080 already in use
  • A TLS setting the server refuses (see Certificate Errors)
  • credentials.yaml still at the pre-0.14.0 path. If the log shows a YAML error that looks like it is reading a directory, the bind mount's host path is missing and Docker created an empty directory in its place. Check with ls -la silo_sdk_mcp/credentials.yaml — if that is a directory rather than a file, see Upgrading from 0.13.x.

Tools Not Appearing (stdio mode)

Symptom: Claude doesn't see the Authentic8 tools

Check:

  • MCP server config file location (it varies by OS)
  • Config file syntax (valid JSON, no trailing commas)
  • Restart client application after editing config

Running a Single Tool from a Shell

To call one tool without any MCP client, use python -m silo_sdk_mcp --call TOOL. It uses the same configuration as stdio mode and refuses state-changing tools unless you add --yes. See Running a tool without an MCP client.

Next Steps