mcp-server-sila
A generic, dynamic Model Context Protocol (MCP) ↔ SiLA 2 bridge for scientists and lab-workflow orchestrators.
Connect SiLA 2 laboratory devices to LLM clients — OpenCode, Claude Desktop, or a custom orchestrator — and operate real hardware in natural language. The bridge exposes each device's real types, units, and constraints as MCP tools, handles SiLA 2's asynchronous and stateful execution model, and gates unsafe actions behind a server-side policy engine and confirmation prompts.
flowchart LR
subgraph client["🧑🔬 Lab agent"]
LLM["LLM client<br/>OpenCode · Claude Desktop<br/>orchestrator"]
end
subgraph bridge["mcp-server-sila"]
direction TB
Tools["Core tools + promoted tools<br/>resources"]
Policy["Policy engine<br/>confirm gate"]
Exec["Execution registry<br/>binary store"]
Disc["mDNS discovery"]
Tools --> Policy --> Exec
end
subgraph lab["Laboratory network"]
direction TB
Mover["Plate mover<br/><i>SiLA 2 server</i>"]
Reader["Plate reader<br/><i>SiLA 2 server</i>"]
Thermo["Thermometer<br/><i>SiLA 2 server</i>"]
end
LLM <-->|"MCP<br/>stdio · streamable-http"| Tools
Exec <-->|"SiLA 2 / gRPC<br/>TLS · mTLS"| Mover
Exec <-->|"SiLA 2 / gRPC"| Reader
Exec <-->|"SiLA 2 / gRPC"| Thermo
Disc -.->|"mDNS / DNS-SD<br/>auto-discovery"| Mover
Disc -.-> Reader
Disc -.-> Thermo
Mover -.->|"labware transfer<br/>(SiLA, device-to-device)"| Reader
classDef clientStyle fill:#15222B,stroke:#15222B,color:#fff
classDef bridgeStyle fill:#41889F,stroke:#2f6d81,color:#fff
classDef labStyle fill:#CDDCE2,stroke:#41889F,color:#15222B
class LLM clientStyle
class Tools,Policy,Exec,Disc bridgeStyle
class Mover,Reader,Thermo labStyle
LLM clients speak MCP to the bridge; the bridge speaks SiLA 2 to the instruments. Instruments can also act on each other over SiLA — a plate mover hands labware to a plate reader, discovered through mDNS.
Why this exists
MCP is request/response; SiLA 2 is long-lived and stateful (execution UUIDs, polling subscriptions, observable properties). The bridge resolves that mismatch with server-side state + pull-style tools:
- an observable command returns
{execution: <uuid>, status}immediately, and the model waits, polls progress, and pulls intermediate responses through separate tools; - binary payloads never flood the context — they are stored and referenced as
sila://binaries/<id>resources; - connection loss and reconnection are handled for you, and every failure the model sees is an actionable message, not an opaque internal error.
Because an LLM can be wrong (or prompt-injected), safety is not delegated to tool annotations: a policy engine decides allow / confirm / deny before any SiLA call is made, and destructive actions require an explicit human confirmation when the client can show one.
Feature highlights
- Two-tier tool model. A stable set of 12 core meta-tools is always present; typed tools for a device's features are generated on demand (with real parameter names, types, units, and constraints) and removed again when no longer needed.
- Full async lifecycle. Observable command tracking by execution UUID, bounded waits, intermediate-response cursors, observable-property polling, and retention-based GC.
- Safety first. Read-only devices, deny globs, destructive-pattern classification, per-device rate and concurrency limits, property-write gating, and a headless fallback that denies destructive actions instead of assuming "yes".
- TLS by default. Four modes —
insecure(loopback only),pinned(CA from mDNS),ca(explicit root CA), andmtls(client certificates). Certificate contents never appear in logs or errors; only paths. - mDNS discovery. Adopt devices as they appear, forget them when they leave (releasing their stored binaries); discovered devices stay read-only until explicitly allowlisted.
- Two transports. stdio for a local client, streamable-http with a static bearer token for remote use — and the server refuses to expose an unauthenticated off-loopback endpoint.
- Hybrid protocol support. Works across MCP protocol eras, using the modern
InputRequiredResultround-trip for confirmations on 2026-07-28+ connections and elicitation on earlier ones. - Operationally boring. One PyPI package, 12-factor configuration, a Docker image, a
redacted
--check-configsummary, and a test suite against a real in-process SiLA 2 device (including TLS and error paths).
Requirements
- Python 3.13
- A SiLA 2 server on the network (any device speaking SiLA 2 over gRPC)
Install
uv tool install mcp-server-sila
# or
pip install mcp-server-sila
Both install the mcp-server-sila console script; python -m mcp_server_sila is
equivalent.
Container
docker build -f docker/Dockerfile -t mcp-server-sila:dev .
docker run --rm -e MCP_SILA_SERVER_HOST=0.0.0.0 -e MCP_SILA_AUTH_TOKEN=change-me \
-p 8765:8765 mcp-server-sila:dev
The image serves streamable-http by default. Mount certificate material at
/opt/mcp-server-sila/certificates (the compose file maps
./docker/mcp-server-sila/certificates there) and reference it by path in the
configuration.
Quick start
stdio — local client (OpenCode, Claude Desktop, …)
Point your MCP client at mcp-server-sila --transport stdio and configure the devices —
either statically (MCP_SILA_ENDPOINT_0_*) or by mDNS discovery (no endpoint
configuration at all). With discovery enabled and an allowlist, the client only needs:
{
"mcpServers": {
"sila": {
"command": "mcp-server-sila",
"args": ["--transport", "stdio"],
"env": {
"MCP_SILA_DISCOVERY_ENABLED": "true",
"MCP_SILA_DISCOVERY_ALLOWLIST": "Plate Mover,Plate Reader"
}
}
}
}
Then ask things like "Which devices are connected?", "What can the pump do?", or "Set the setpoint to 42 and tell me when it's done." The exact configuration for OpenCode and Claude Desktop, including the remote variant, is in Connect a client.
streamable-http — remote / orchestrator
MCP_SILA_AUTH_TOKEN=change-me MCP_SILA_SERVER_HOST=0.0.0.0 \
mcp-server-sila --transport streamable-http --port 8765
The endpoint is http://<host>:8765/mcp; clients send
Authorization: Bearer change-me. A non-loopback host without a token is refused at
startup.
Validate a configuration without serving
mcp-server-sila --config bridge.toml --check-config
# prints a redacted summary and exits 0 (errors exit 2)
Connect a client
Any MCP client works. The bridge serves stdio (the client starts it as a child process) or streamable-http (a URL plus a bearer token). Confirmation prompts and tool-list changes are supported on both protocol eras; see the notes below.
OpenCode
OpenCode's V2 configuration declares MCP servers under mcp.servers — in
opencode.jsonc for a project or in the global config.
local (stdio) — OpenCode starts the bridge itself:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"servers": {
"sila": {
"type": "local",
"command": ["mcp-server-sila", "--transport", "stdio"],
"environment": {
"MCP_SILA_DISCOVERY_ENABLED": "true",
"MCP_SILA_DISCOVERY_ALLOWLIST": "Plate Mover,Plate Reader"
},
"protocol": "auto"
}
}
}
}
The same entry can be created from the CLI:
opencode mcp add sila \
--env MCP_SILA_DISCOVERY_ENABLED=true \
--env MCP_SILA_DISCOVERY_ALLOWLIST="Plate Mover,Plate Reader" \
-- mcp-server-sila --transport stdio
opencode mcp list # expect: ✓ sila connected
remote (streamable-http) — for a bridge running elsewhere (or in a container):
{
"mcp": {
"servers": {
"sila": {
"type": "remote",
"url": "http://127.0.0.1:8765/mcp",
"oauth": false,
"headers": { "Authorization": "Bearer {env:MCP_SILA_TOKEN}" },
"protocol": "auto"
}
}
}
}
oauth is set to false because the bridge uses a static bearer token, not OAuth;
{env:MCP_SILA_TOKEN} keeps the secret out of the configuration file. /mcps in the TUI
shows the connection state, and OpenCode's default Code Mode groups the tools under
tools.sila.*.
Claude Desktop
Claude Desktop uses mcpServers in claude_desktop_config.json:
{
"mcpServers": {
"sila": {
"command": "mcp-server-sila",
"args": ["--transport", "stdio"],
"env": {
"MCP_SILA_DISCOVERY_ENABLED": "true",
"MCP_SILA_DISCOVERY_ALLOWLIST": "Plate Mover,Plate Reader"
}
}
}
}
Protocol eras and confirmations
The bridge speaks both MCP protocol eras:
- Modern (2026-07-28) — selected by OpenCode's
"protocol": "auto"(or"2026-07-28"). Confirmation prompts arrive as an input-required round-trip and are shown as forms. - Legacy (up to 2025-11-25) — OpenCode's default (
"legacy") and what most clients use today. The bridge asks for confirmation through classic elicitation, which clients that support it (including OpenCode) render as a form.
Clients that cannot show a prompt never get a silent "yes": destructive actions are denied (see Safety & security).
No endpoint configuration needed
With MCP_SILA_DISCOVERY_ENABLED=true, the bridge finds SiLA servers on the network by
itself — nothing else to configure. Ask the agent "Which SiLA devices are on the
network?", then "Promote the plate mover's feature and hand the plate to the reader."
See Discovery (mDNS / Bonjour) for the mechanics and
examples/sila-labware-transfer
for a working two-server lab.
How it works
The tool model
- Core meta-tools (always present) work on any device, addressed by alias, short identifier, fully qualified identifier (FQID), or UUID prefix.
- Promoted typed tools are generated per feature on demand. They behave like native MCP tools — typed parameters, JSON-Schema constraints, units in the description, and structured output — and disappear when demoted or when their device is lost.
| Core tool | What it does |
|---|---|
sila_list_devices |
All known devices with lifecycle state (connected/connecting/lost) |
sila_describe_device |
Identity plus the full feature tree (properties, commands, types, units) |
sila_list_features |
Lighter feature summary for a device |
sila_read_property |
Current value (observable properties: first value) |
sila_write_property |
Write a value (policy-gated; confirmation by default) |
sila_execute_command |
Execute a command: responses, or {execution, status} for observable ones |
sila_poll_property |
Changed values within a bounded window (capped, with a true count) |
sila_execution_info |
Status, progress, remaining time of a tracked execution |
sila_wait_execution |
Bounded wait → final responses, error, or "still running" |
sila_execution_intermediate |
Intermediate responses since a cursor |
sila_promote_feature |
Generate typed tools for alias/*, alias/Feature, or an FQID |
sila_demote_feature |
Remove a feature's typed tools |
Element tools (read_property, write_property, execute_command, poll_property)
accept an optional device argument. When several connected devices implement the same
FQID and no device is given, the call is refused rather than guessing — actuating the
wrong instrument is worse than an actionable error.
Resources
| URI | Content |
|---|---|
sila://{device}/{feature}/{property} |
A property's current value as JSON text |
sila://binaries/{id} |
Bytes of a stored binary value (application/octet-stream) |
Binary values (properties or command responses) are stored in an ephemeral store with a
10 MB per-value and 500 MB per-device cap, returned to the model as
{"$binary": size, "type": "binary", "uri": "sila://binaries/<id>"}, and cleaned up when
their execution leaves the retention window, when the device leaves discovery, or after
one hour.
Architecture
poolowns onesila.client.Clientper device, reconnects with exponential backoff, and fires lifecycle events.discovery_watcherbridges mDNS discovery into pool adoption/removal.policymakes allow/confirm/deny decisions before any RPC.tools/confirmturns "confirm" into an MCP elicitation round-trip (or the headless policy fallback).executiontracks observable executions by UUID with retention GC.binaryis the ephemeral value store;values/schematranslate between SiLA types and JSON.serverassembles the MCP server, core tools, resources, and lifespan;cliruns the transport.
See docs/architecture.md for the component table and lifecycle diagram, and the design specification for the full rationale.
Discovery (mDNS / Bonjour)
SiLA 2 servers announce themselves with multicast DNS / DNS-based Service Discovery — the
same Bonjour/Avahi mechanism printers and Chromecasts use. The bridge consumes those
announcements to find and configure devices, and (for configured pinned endpoints)
resolves a device's CA certificate from them.
What a SiLA server advertises
Over IPv4 multicast (UDP 5353) a server publishes, under the service type
_sila._tcp.local.:
| Record | Content |
|---|---|
| PTR | _sila._tcp.local. → <uuid>._sila._tcp.local. |
| SRV | host and port of the gRPC endpoint |
| TXT | server_name, description, version, and — when TLS is enabled — the CA certificate as ca0, ca1, … lines |
| A | the IPv4 address(es) to connect to |
On shutdown the server sends an mDNS "goodbye". Most SiLA 2 SDKs advertise automatically:
the unitelabs-cdk (used by the copier templates) enables it by default and lets you tune
it in the discovery: section of its config.
What the bridge does with it
- Browse. The discovery watcher runs a DNS-SD browser and snapshots the service table once a second (the library's change notification is private).
- Adopt. A new service becomes a device: alias = advertised
server_name, endpoint = SRV/A address and port, TLS = CA-pinned to the TXT certificate. Adoption never blocks startup — a failing connection staysconnecting/lostand is retried with backoff. - Allowlist.
discovery.allowlist(UUIDs or names, case-insensitive) decides access: listed → full access (subject to the policy engine); empty → everything is adopted read-only and a warning is logged; not listed → the service is ignored entirely. - Forget. A departed service (goodbye packet) is removed from the pool, its client is closed and its stored binaries are released.
- Pin TLS for configured endpoints. A configured endpoint with
tls = "pinned"and no known CA triggers a one-shot mDNS lookup by the endpoint's name and uses the advertised certificate as the trust anchor. If nothing answers, the connection fails with a message suggestingtls = "ca"plus aca_certpath.
Enable it in the configuration file:
[discovery]
enabled = true
allowlist = ["Plate Mover", "Plate Reader"] # names or UUIDs
or through the environment:
MCP_SILA_DISCOVERY_ENABLED=true \
MCP_SILA_DISCOVERY_ALLOWLIST="Plate Mover,Plate Reader" \
mcp-server-sila --transport stdio
Practical notes
- Discovery needs a shared multicast domain: the same LAN,
network_mode: hostin Docker, or an mDNS reflector (e.g. Avahi in bridge mode). A container on Docker's default bridge network does not see the lab's multicast. avahi-browse -rt _sila._tcp(ordns-sd -B _sila._tcp) lists what the network actually advertises; the bridge logsDiscovered SiLA server '<name>' (<uuid>) ….- A device can be configured statically and discovered at the same time: a discovered
service that matches a known endpoint is not adopted twice, and
ca_certalways wins over a discovered CA. - A complete worked example — two copier-generated servers (plate mover and plate reader), mDNS-only bridge configuration, and a plate transfer plus read over MCP — is in examples/sila-labware-transfer.
Configuration
The bridge is 12-factor: a TOML file (--config PATH or $MCP_SILA_CONFIG) plus
MCP_SILA_* environment variables, which win per key. CLI flags win over both.
A minimal file:
[server]
transport = "stdio" # stdio | streamable-http
host = "127.0.0.1" # streamable-http only
port = 8765
log_level = "INFO"
[[endpoint]]
name = "pump1" # alias used in tool names and references
address = "192.168.1.40"
port = 50065
tls = "pinned" # insecure | pinned | ca | mtls
# ca_cert = "/srv/certs/lab-ca.pem" # tls = ca | mtls
# client_cert = "/srv/certs/mcp.pem" # tls = mtls
# client_key = "/srv/certs/mcp.key"
The full key reference, defaults, environment-variable mapping, and validation rules live in docs/configuration.md. The important defaults:
| Setting | Default |
|---|---|
| Transport / port | stdio · 8765 (streamable-http path /mcp) |
| Discovery | disabled; discovered devices read-only until allowlisted |
| Confirmation | destructive commands and property writes |
| Rate limits | 10 commands/min and 4 concurrent executions per device |
| Promotion | enabled, max 200 tools, none auto-promoted |
| Execution retention | 600 s; sila_wait_execution capped at 300 s |
Safety & security
The short version; details in docs/security.md.
-
Policy engine is the enforcement point. Every write and command is checked first: read-only devices and deny globs reject immediately; destructive commands and property writes require confirmation; rate and concurrency limits bound the traffic.
-
Confirmation degrades to policy, never to "always yes". Interactive clients get an elicitation form (
proceed/reason). Clients that cannot answer (unattended orchestrators) get: destructive → denied, non-destructive → allowed — and underconfirm_all_commandseverything is denied. -
Discovered devices are read-only until allowlisted. mDNS adoption alone never grants write or execute access.
-
TLS modes:
Mode Trust anchor When insecurenone (loopback only — validated) local development pinnedthe CA in the device's mDNS TXT record (one-shot lookup for configured endpoints) self-signed lab devices caan explicit ca_certpathlab PKI mtlsany of the above plus client_cert/client_keydevices requiring client auth ca_certalways wins over a discovered CA; PEM contents are never logged or returned. -
Bearer token for streamable-http. Compared in constant time; required whenever the host is not loopback; set via config or
MCP_SILA_AUTH_TOKENonly (never a CLI argument). -
Untrusted metadata. Device descriptions are truncated into tool descriptions, the server instructions say metadata is data (not instructions), and values are capped (4 KB text, 100-element lists, binaries by reference).
-
Annotations are hints, not security.
readOnlyHint/destructiveHintinform clients; enforcement never depends on them.
CLI reference
mcp-server-sila [--config PATH] [--transport {stdio,streamable-http}]
[--host HOST] [--port PORT] [--log-level LEVEL]
[--check-config]
--config PATH— TOML file (default$MCP_SILA_CONFIG).--transport,--host,--port,--log-level— override the configuration.--check-config— validate, print a redacted summary, exit 0 (or 2 with the aggregated error).
Exit codes: 0 success, 2 configuration/auth errors.
Development
uv sync # create the environment (Python 3.13)
uv run pytest # full suite (in-process SiLA 2 test device)
uv run ruff check --fix . # lint + import order
uv run ruff format . # formatting (line length 120)
uv run zuban check # static types (src/ and tests/)
uv run --group docs python -m sphinx -b html docs /tmp/docs-build
uv build # wheel + sdist
The suite covers the bridge end-to-end through an in-memory MCP client against a real in-process SiLA 2 server: device discovery and reconnection, command execution and error mapping, confirmations in both protocol eras, policy decisions, TLS with ephemeral certificates, bearer-token auth, binary round-trips, and GC.
Project layout: src/mcp_server_sila/ (package), tests/ (mirrors it, plus
tests/fixtures/sila_device.py), docs/ (user documentation; the design and plan live in
docs/development/), docker/ (image + entrypoint).
Documentation
Rendered documentation: https://opensourcelab.gitlab.io/sila/mcp-server-sila/
- User guide
- Installation
- Connecting a client
- Your first workflow
- Device discovery (mDNS)
- Sequences & orchestration
- Developer guide
- Tool catalogue
- Configuration reference
- Security model
- Architecture
- Design specification
Status
0.x — pre-1.0. All core capabilities are implemented and tested: the core tool set, typed tool promotion, policy and confirmation gates, TLS modes, mDNS discovery, binary resources, and both transports. Planned for later releases: push-based resource subscriptions, full OAuth for streamable-http, and re-adopting in-flight executions after a bridge restart.
License
MIT — see LICENSE.
Metadata
Release files for mcp-server-sila 0.0.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mcp_server_sila-0.0.3.tar.gz | 78.3 kB | Without provenance | Details for mcp_server_sila-0.0.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mcp_server_sila-0.0.3-py3-none-any.whl | Python 3 | none | any | Details for mcp_server_sila-0.0.3-py3-none-any.whl |
Total release size: 156.4 kB
Release files / mcp_server_sila-0.0.3.tar.gz
| Download URL | mcp_server_sila-0.0.3.tar.gz |
|---|---|
| Size | 78.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c236de8568d92dcf0dec00b874496eef30ccf1dde5dcedc5b20d5288cce06d4a
|
|
BLAKE2b-256 checksum How to use checksums |
6778c019b1e81f401a08fb9f88bf24b55959150a901f8c670c33551465700134
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.18
|
Release files / mcp_server_sila-0.0.3-py3-none-any.whl
| Download URL | mcp_server_sila-0.0.3-py3-none-any.whl |
|---|---|
| Size | 78.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
70bac003f495e0e337643a4de41e50b8b51b923c4de8681aacd620787fbcdd51
|
|
BLAKE2b-256 checksum How to use checksums |
cddc24eb0d44369efdf6fa82fd35957e538fae5f72c14766b8847d6bdbec76dd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.18
|
Security for mcp-server-sila 0.0.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.