droid-mcp-core/io.droidmcp.core.transport/HttpTransport

HttpTransport

class HttpTransport(registry: ToolRegistry, port: Int = 8080, bearerToken: String? = null, requireAuth: Boolean = true, readOnly: Boolean = false, context: Context? = null, serverVersion: String = DROID_MCP_VERSION, auditSink: AuditSink? = null, tls: TlsConfig? = null, allowedOrigins: Set<String> = emptySet(), resources: ResourceRegistry = ResourceRegistry(), prompts: PromptRegistry = PromptRegistry())

Ktor/Netty MCP server for desktop clients, speaking the Streamable HTTP transport. Exposes the JSON-RPC surface at POST /mcp (plus GET /mcp for the server stream, DELETE /mcp to end a session, and a /health probe), enforces bearer auth via a TokenStore when requireAuth is set, optionally terminates TLS, and advertises itself over mDNS (_mcp._tcp). Prefer building one through DroidMcp.Builder.enableHttpServer rather than directly.

Request hardening, applied before any tool runs:

an Origin header outside allowedOrigins is rejected with 403 (DNS-rebinding / drive-by browser protection — native MCP clients send no Origin);
POST bodies must be application/json (415 otherwise) and at most MAX_BODY_BYTES (413);
an MCP-Protocol-Version header outside McpProtocolImpl.SUPPORTED_PROTOCOL_VERSIONS is rejected with 400;
every request after initialize must carry the Mcp-Session-Id issued to the same client (400 when missing, 404 when unknown or owned by another client).

A tools/call that reports progress or asks for elicitation answers with an SSE stream (when the client accepts text/event-stream); every other reply is plain JSON. GET /mcp opens the session's standalone SSE stream (one per session; a new one replaces the old), which carries notifications/{tools,resources,prompts}/list_changed whenever registry, resources or prompts change, plus a keep-alive comment every KEEPALIVE_MS ms.

Parameters

registry

Tools to serve.

port

Plaintext port; overridden by TlsConfig.httpsPort when tls is set.

bearerToken

Fixed primary token (at least MIN_TOKEN_LENGTH characters); a random one is generated when null and requireAuth is true.

requireAuth

Require a Bearer token on every request. When false the server is open.

readOnly

Serve only read-only tools.

context

Android context for mDNS registration; mDNS is skipped when null.

serverVersion

Version reported in initialize and the mDNS TXT record.

auditSink

Optional per-call audit hook.

tls

TLS material; when set the server binds HTTPS and exposes tlsFingerprint.

allowedOrigins

Exact Origin values (scheme://host:port) permitted to call the server.

resources

Resource providers served by the resources/... methods.

prompts

Prompts served by the prompts/... methods.

Throws

IllegalArgumentException

if bearerToken is shorter than MIN_TOKEN_LENGTH.

Constructors

HttpTransport

constructor(registry: ToolRegistry, port: Int = 8080, bearerToken: String? = null, requireAuth: Boolean = true, readOnly: Boolean = false, context: Context? = null, serverVersion: String = DROID_MCP_VERSION, auditSink: AuditSink? = null, tls: TlsConfig? = null, allowedOrigins: Set<String> = emptySet(), resources: ResourceRegistry = ResourceRegistry(), prompts: PromptRegistry = PromptRegistry())

Types

Companion

object Companion

Properties

effectiveToken

val effectiveToken: String?

Current primary token, or null on an open server. Tracks rotateToken.

isTlsEnabled

val isTlsEnabled: Boolean

Whether the server terminates TLS.

mdnsServiceName

val mdnsServiceName: String

mDNS service name advertised on the network, derived from the device model (sanitised, ≤63 chars).

tlsFingerprint

val tlsFingerprint: String?

SHA-256 fingerprint of the server certificate to pin in the pairing QR, or null when TLS is disabled. See TlsConfig.certFingerprintSha256.

Functions

isRunning

fun isRunning(): Boolean

Whether the embedded server is currently running.

pairClient

fun pairClient(label: String): String?

Mint a revocable token for a named client. Re-pairing an existing label replaces its token. Returns the new token, or null on an open server.

pairedClients

fun pairedClients(): List<TokenStore.PairedClient>

Snapshot of paired clients (excludes the primary). Empty on an open server.

revokeClient

fun revokeClient(label: String): Boolean

Revoke a paired client's token. @return true if a client with that label existed.

rotateToken

fun rotateToken(): String?

Rotate the primary bearer token, invalidating the old one. Paired-client tokens are unaffected. Returns the new token, or null on an open server. Surface the new value in a fresh pairing QR.

start

@Synchronized

fun start()

Start the embedded server and register mDNS. No-op if already running; rethrows bind failures. Synchronized with stop so concurrent start/stop can't orphan a bound server.

stop

@Synchronized

fun stop()

Stop the server and unregister mDNS. No-op if not running.