Client Security

An MCP client connects your application, and often an LLM acting for your users, to code you do not control. This guide summarizes what the client assumes, what it does by default, and what remains your job.

Threat model

Treat everything that comes from a server as untrusted input:

• Servers. A server may be malicious, compromised, or simply buggy. Its self-reported serverInfo.name is display data only; the client identifies servers by the operator-assigned server_id.
• Tool definitions. Names, descriptions, schemas and annotations are server-written. A description can carry instructions aimed at the model ("tool poisoning"), a name can imitate another tool, a schema can be pathological, and a definition can change after you approved it ("rug pull").
• Tool results, resources, prompts and instructions. Anything a server returns can try to steer the model (prompt injection), including into calling another server's tool with data it just read (cross-server exfiltration).
• Server requests. Sampling, elicitation and roots requests let a server ask for model calls, user input and local paths.

The client's stance on prompt injection is flag, don't solve. Injection cannot be detected reliably, so the client does not try. It removes the characters that hide text from humans, caps sizes, never fetches what a server points at, records what it changed in provenance, and gives the host the hooks to decide: tool filters, a policy with fixed precedence, approvals bound to exact arguments, fingerprint pinning, and taint rules. See client_permissions_and_hooks.md.

Security defaults

Every value below is the default. Each is enforced in code; the module named is where it lives.

Tools and governance

Content for models

Server requests

Connections

stdio

ConduitMcp.Client.Transport.Stdio runs a local process as this VM's user.

Know the limits:

• Configuration is operator-only. Whoever chooses :command, :args and :env runs code as your VM's user. Never build them from model output, server responses or end-user input, and treat imported server configs (for example from a desktop app's JSON) as code to review.
• The env allowlist is hygiene, not isolation. The server still runs as your user, with your file system and network.
• No stderr capture. stderr goes to this VM's stderr (:inherit), is discarded, or appended to a file (:discard and {:file, path} are POSIX only). It is never parsed or logged by the client.
• Grandchildren may survive. Launchers such as npx and uvx start the real server as a child. Closing stdin normally ends both, but the signals reach only the launcher's pid, so a grandchild that ignores EOF can outlive it.
• A killed port owner only closes stdin. If the port owner itself is killed (Process.exit(pid, :kill), the VM halting), a server that ignores EOF keeps running.
• PID reuse. The pid is signalled after the port is closed, so reuse in that window is possible in theory.

When these matter, run servers under a wrapper that bounds and kills them: a container, systemd-run --user --scope -p MemoryMax=..., prlimit for resource limits, or MuonTrap for kill-on-parent-exit.

Streamable HTTP

Server URL policy

server_url_policy: :any (default) trusts the URL: right for operator configuration. When the URL comes from end users, use :public_only:

{ConduitMcp.Client.Transport.StreamableHTTP,
 url: user_supplied_url,
 server_url_policy: :public_only,
 allow_private: ["10.20.0.0/16"]}

:public_only applies ConduitMcp.Client.URLPolicy before every request: https only, and the host is resolved (A and AAAA) and refused if any address is private, loopback, link-local, multicast or otherwise internal, unless it falls inside an :allow_private CIDR. Hosts are parsed, never string-matched: 127.1, 0x7f.1, 2130706433 and [::ffff:127.0.0.1] are all loopback. URLs with user info, percent-encoded or non-ASCII hosts, IPv6 zone ids, backslashes or control characters are refused.

ConduitMcp.Client.URLPolicy.check("https://127.1/", :public_only)
#=> {:error, {:blocked_address, {127, 0, 0, 1}}}

The request then connects to the first vetted address, never resolving the name again, so a DNS answer that changes between the check and the connect (rebinding) cannot send it elsewhere. TLS SNI, certificate verification and the Host header all use the URL's host name. Each request (the legacy GET stream and session DELETE included) is checked and pinned in its own process; resolver: replaces DNS for the check, and runs there too, never in the connection. The pinned connections come from pools the transport starts in the Finch instance, yours with finch: included: one per vetted address, sized by :pool_size, with :transport_opts as TLS options.

What this guarantees, and what it does not:

• Every byte goes to an address that passed the policy at that request. A later request resolves and vets the name again, so a pool may hold connections to every address the host has had.
• The certificate check is the binding to the name. That is why :public_only together with insecure_skip_tls_verify: true raises at start: without verification, whoever answers at the vetted address (or on the path to it) gets the request and its credentials.
• Public addresses are still reachable. The policy keeps requests away from internal networks; it does not vouch for the public server the user named.

Secrets

Wrap credentials in ConduitMcp.Client.Secret:

token = ConduitMcp.Client.Secret.new(System.fetch_env!("DOCS_TOKEN"))

inspect(token)                          #=> "#Secret<redacted>"
ConduitMcp.Client.Secret.expose(token)  #=> the value, where it belongs

The client holds bearer tokens, legacy session ids, MRTR requestState and :env/:headers values given as secrets this way. A Secret does not guard against raw term printing (:sys.get_state/1, :erlang.term_to_binary/1); client processes that hold one implement format_status/1 to redact their state.

Elsewhere:

• ConduitMcp.Client.Error messages render only the kind and a truncated reason; data (which may hold server content) is never rendered.
• Client telemetry metadata comes from a fixed allowlist: no _meta, tokens or raw error data, and no arguments or results by default. Tool names and methods are sanitized, and are server-supplied, so never use them as metric tags.
• Payload capture is opt-in (TL-2). telemetry: [capture_payloads: [redact: fun, max_bytes: n]] adds :arguments to the tool_call span's :start and :result to its :stop. Redaction is mandatory (capture_payloads: true raises when the client starts); fun runs in the calling process before any handler sees the value. A value whose JSON is over :max_bytes (default 4 096) becomes {:truncated, byte_size}, never a partial value; a redact that raises, or returns something that cannot be JSON-encoded, gives :redaction_failed, never the raw value. A ConduitMcp.Client.Secret left in place refuses to encode, so it gives :redaction_failed too. No hash or digest of the arguments is offered: low-entropy arguments are brute-forceable from one. With the default false neither key is present.
• Finch's own telemetry is not the client's. The [:finch, ...] events carry the request in their metadata, its headers included: the clear-text Authorization and Mcp-Session-Id. Never log or export Finch telemetry metadata wholesale; pick the fields you need.
• Server log entries (notifications/message) are rate limited per connection (:log_rate_limit, 50/s with bursts of 100; drops emit [:conduit_mcp, :client, :log, :dropped]) and reach subscribers and handle_log/3 with every string passed through ConduitMcp.Reflect.text/2 and the level clamped to the RFC 5424 set, so a server cannot forge your log lines.
• Trace context: only a well-formed W3C traceparent (from the :traceparent request option or Logger.metadata()[:traceparent]) is propagated in a modern request's _meta; tracestate and baggage never are.
• Hooks: what a failing hook raised is never logged or emitted.
• Task ids are bound to the credential that created them and may act as bearer tokens: never log them.
• Private cached results are keyed by credential (HT-11, enforced): a list the server marks cacheScope: "private" (or leaves unmarked) is served only while the client sends the credentials it was fetched with, and is deleted when they change (ConduitMcp.Client.set_auth/3, OAuth for another principal). The key is a digest: the token's SHA-256, the OAuth {principal, issuer, resource}, or an :auth function's :credential_id. Without a :credential_id an :auth function's private results are never served from the cache. See "Private results and credentials" in client.md.
• Grants and the approval baseline belong to one client: pass principal: on calls, or run one client (or hub) per user when users differ.

ui:// resources

MCP Apps servers return self-contained HTML as ui:// resources (see mcp_apps.md). The client reads them like any other resource and does not render, sanitize or execute them. Rendering is the host's job, and that HTML is server-written: show it only in a sandboxed iframe on an origin separate from your application, with a restrictive Content Security Policy, and never give it your session, cookies or tokens.