MCP: configurable HTTPS enforcement for seed-based tools

[jasminecheong]

Context

The CAD (design/docs/cad/041_mcp/index.md) correctly warns that seed-based tools (transact, signAndSubmit, transfer) transmit the Ed25519 seed over the network and therefore require HTTPS. But nothing in the server enforces this — a misconfigured peer running plain HTTP would happily accept and forward seeds in cleartext.

Enhancement

Enforce HTTPS for seed-bearing MCP tool calls, configurable via peer config.

Suggested shape:

• mcp.requireHttps.seedTools = true (default) | false
• When true: if a request for transact, signAndSubmit, transfer, or signingImportKey arrives over plain HTTP (no TLS termination marker), respond with a JSON-RPC error (e.g. -32600 with a clear message) rather than processing the seed.
• Detect TLS via the usual signals: request.isSecure(), X-Forwarded-Proto: https from a trusted reverse proxy, or an explicit peer-config flag stating "I am behind a TLS-terminating proxy".

Considerations

• Default must be true — the silent-cleartext-seed failure mode is exactly the kind of thing users expect the platform to prevent.
• Local development is the main reason to allow HTTP. Provide a clear override (e.g. mcp.requireHttps.seedTools: false) with a startup log warning when it is disabled.
• Reverse-proxy deployments need a way to declare that upstream HTTP is acceptable because TLS is terminated externally. X-Forwarded-Proto trust must itself be configurable to avoid header spoofing.
• This extends naturally to signingImportKey and signingExportKey, which carry key material even though they are not "seed-based" in the narrow sense.
• Document the recommended production config in the CAD security section.

Related

• CAD: design/docs/cad/041_mcp/index.md § Security Considerations

[brittleboye]

Design proposal

Posting for discussion before I land the PR. Happy to adjust any of this.

Secret-bearing tool set

Five tools where a seed (or equivalent key material) crosses the network boundary:

• transact — seed in request body
• signAndSubmit — seed in request body
• transfer — seed in request body
• signingImportKey — seed in request body
• signingExportKey — seed in response body

The issue lists the first four. I'd add signingExportKey because the exposure mode (seed on the wire in cleartext) is identical — just the other direction. Open to dropping it if the feeling is that exports are rare enough not to care.

Config shape

Two peer-config keys, both under the mcp section (extending RESTConfig):

Key	Type	Default	Purpose
mcp-require-https	boolean	true	Master switch — when false, no enforcement
mcp-trust-proxy	boolean	false	If true, honour X-Forwarded-Proto: https

A request counts as "secure" if any of:

1. ctx.scheme().equals(\"https\") — direct TLS
2. mcp-trust-proxy=true and X-Forwarded-Proto: https — TLS-terminating proxy upstream

If mcp-require-https=true and the tool is in the secret-bearing set and the request is not secure → reject with JSON-RPC error -32600 ("Invalid Request: this tool requires HTTPS"), before the tool handler runs. No seed reaches the dispatch path.

The X-Forwarded-Proto trust has to be opt-in: without mcp-trust-proxy, a malicious client could spoof the header and bypass enforcement.

Wiring

Rather than subclassing McpServer or forking toolCall, I'd add a generic pre-dispatch hook on McpServer:

@FunctionalInterface
public interface ToolCallInterceptor {
    /** Return null to allow, or a JSON-RPC error map to reject. */
    AMap<AString, ACell> check(String toolName, Context ctx);
}

public void setToolCallInterceptor(ToolCallInterceptor i) { ... }

McpServer.toolCall(...) invokes it once, before tool lookup. McpAPI registers its HTTPS-enforcement interceptor in its constructor.

Benefits:

• McpServer stays policy-free — other consumers (e.g. Covia venues) aren't forced into Convex-specific rules.
• Future issues (MCP: configurable Origin validation for DNS rebinding protection #552 origin validation, per-identity rate limiting, audit logging) can be composed on the same hook rather than each growing its own place in dispatch.
• Interceptor runs before the tool handler, so no seed enters the CVM or signing paths on a rejected call.

Startup warning

When a peer starts with mcp-require-https=false, emit a WARN-level log at startup: "MCP HTTPS enforcement disabled — seed-based tools will accept cleartext connections. This is appropriate for local development only." Makes the weakened posture visible in logs rather than silent.

Tests

This is the main design question, because existing MCP tests run over plain HTTP on localhost. Two options:

(a) Tests opt out, new focused suite opts in. ARESTTest launches the peer with mcp-require-https: false, so current tests pass unchanged. A new McpHttpsEnforcementTest spins up its own RESTServer with enforcement on and verifies that each secret-bearing tool is rejected over HTTP and accepted via trusted-proxy X-Forwarded-Proto: https.

(b) Runtime-mutable flag. Keep one shared fixture, expose a package-private setter on McpAPI, flip it inside each enforcement test and flip it back in an @AfterEach.

(a) is cleaner architecturally — the test mirrors how the config flows in production. (b) is cheaper boilerplate but adds a test-only mutator to production code and bakes in ordering assumptions.

Preference: (a). Willing to do (b) if the fixture-overhead worry outweighs the policy question.

CAD041 update

Add to the Security Considerations section:

HTTPS enforcement — peers MUST serve seed-bearing tools (transact, signAndSubmit, transfer, signingImportKey, signingExportKey) only over HTTPS. The mcp-require-https config key (default true) enforces this at dispatch time, rejecting plain-HTTP calls with JSON-RPC error -32600 before any seed reaches the signing path. Reverse-proxy deployments set mcp-trust-proxy=true to honour X-Forwarded-Proto: https from a trusted upstream. Disabling enforcement is appropriate for local development only and emits a startup WARN so operators see the weakened posture in logs.

Open questions

1. Include signingExportKey in the set? (I say yes — seed leaves the server in cleartext.)
2. Test approach (a) vs (b)?
3. Should mcp-trust-proxy grow into a list of trusted proxy IPs/CIDRs later, or is a simple boolean sufficient? For now I'd ship the boolean and revisit if someone needs finer-grained control.
4. Should any tool in the signing-service set beyond import/export be blocked too? signingSign and signingTransact both take a passphrase over the wire — same class of risk as a seed. Argument for adding them; argument against is the set grows and the config starts feeling ad-hoc. Inclined to keep it to the five above and open a separate issue if passphrase-bearing tools need the same treatment.

Feedback welcome — will open the PR once the set and test approach are settled.