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.
From GitHub Release (Recommended)¶
# 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.
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.
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).
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:
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:
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:
You should see output listing all 76 tools:
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:
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:
credentials.yamlis volume-mounted into the container (read-only). It maps each client Bearer token to a set of${VAR}references.- The actual token values are injected as environment variables via
--env-fileorenv_file:in Docker Compose. The MCP server resolves${VAR}references incredentials.yamlagainst 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.
| 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.
| 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.
| 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.
| 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:
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:
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:
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:
View logs:
Stop the server:
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:
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:
- Restart the application (Claude Desktop, Claude Code, etc.)
- Check the MCP connection status (usually shown in settings or status bar)
- 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*.logfiles in~/Library/Logs/Claude/(macOS) or%APPDATA%\Claude\logs\(Windows) - Claude Code: run
/mcpin a session to see each server's status, or start Claude Code withclaude --debugfor verbose MCP output - Other clients: see the client's documentation for its log location
- Claude Desktop:
- Verify the client's
envblock (or Claude Code's-eflags) 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.envcontains them - Ensure absolute paths in config (no
$HOME,~, or relative paths) - Verify the
silo-sdk-mcpbinary 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.
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 usehttps://, 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) orenv_file: .env.http(Compose) is present - Check that variable names in
.env.httpmatch exactly whatsilo_sdk_mcp/credentials.yamlreferences (e.g.,ALICE_ADMIN_TOKENin.env.httpmust match${ALICE_ADMIN_TOKEN}in the YAML) - Ensure
${VAR}syntax is used in the YAML — not$VARor{VAR} - Review server startup logs for credential loading warnings:
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 certificateorunable to verify the first certificate: the client does not trust the CA. SetNODE_EXTRA_CA_CERTSfor Node.js clients (see Making the client trust the certificate), or add the missing intermediate certificates to the end oftls.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 requiredorbad 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:
Common causes:
credentials.yamlfile 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.yamlstill 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 withls -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¶
- Tool Reference - Browse all 76 available tools
- API Reference - Explore the underlying SDK methods