Module server 

MCP server setup and lifecycle.

Implements an rmcp-based MCP server over stdio or HTTP transport.

Transport Security Model (COMP-CRIT-003)

Stdio Transport (Default)

The stdio transport is the default and recommended transport for local use with Claude Desktop and other MCP-compatible clients. Its security model is based on:

Trust Assumptions:

• Process isolation: The parent process (Claude Desktop) spawns subcog as a child process. Communication happens exclusively over stdin/stdout pipes.
• No network exposure: Stdio transport never binds to a network port, eliminating remote attack vectors entirely.
• Same-user execution: The spawned process inherits the parent’s user context, meaning file system and secret access is limited to what the invoking user can access.
• No authentication required: Since only the parent process can communicate over the pipes, authentication is implicit through OS process isolation.

Security Properties:

• Confidentiality: Data never leaves the local machine unless explicitly requested (e.g., git sync to remote).
• Integrity: OS guarantees pipe integrity; no MITM attacks possible.
• Availability: Process lifecycle is controlled by the parent.

Threat Mitigations:

• Malicious input: Content is sanitized before storage (secrets detection, PII redaction).
• Resource exhaustion: Rate limits and memory caps protect against DoS.
• Privilege escalation: Subcog runs with user privileges, never elevated.

HTTP Transport (Optional)

The HTTP transport exposes subcog over a network socket and requires explicit security:

• JWT bearer token authentication (SEC-H1): All requests must include a valid JWT. Requires SUBCOG_MCP_JWT_SECRET environment variable (min 32 characters).
• Per-client rate limiting (ARCH-H1): Prevents abuse via configurable request limits.
• CORS protection (HIGH-SEC-006): Restrictive by default; origins must be explicitly allowed.
• Security headers: X-Content-Type-Options, X-Frame-Options, CSP, no-cache directives.

When to use HTTP transport:

• Remote access to subcog server (e.g., from containerized environments)
• Shared team server with multi-user access
• Integration with web-based MCP clients

Configuration:

# Required for HTTP transport
export SUBCOG_MCP_JWT_SECRET="your-32-char-minimum-secret-key"

# Optional: customize rate limits
export SUBCOG_MCP_RATE_LIMIT_MAX_REQUESTS=1000
export SUBCOG_MCP_RATE_LIMIT_WINDOW_SECS=60

# Optional: configure CORS for web clients
export SUBCOG_MCP_CORS_ALLOWED_ORIGINS="https://your-app.com"

Structs

CorsConfig

CORS configuration (HIGH-SEC-006).

HttpAuthState 🔒

McpHandler 🔒

McpServer

MCP server for subcog.

McpState 🔒

RateLimitConfig

Rate limit configuration (ARCH-H1).

RateLimitEntry 🔒

Enums

Transport

Transport type for the MCP server.

Constants

DEFAULT_CORS_ALLOWED_ORIGIN 🔒

Default allowed CORS origin (none by default for security).

DEFAULT_RATE_LIMIT_MAX_REQUESTS 🔒

Default maximum requests per rate limit window.

DEFAULT_RATE_LIMIT_WINDOW_SECS 🔒

Default rate limit window duration (1 minute).

Statics

SHUTDOWN_REQUESTED 🔒

Global shutdown flag for graceful termination (RES-M4).

Functions

auth_middleware 🔒

await_shutdown 🔒

build_cors_layer 🔒

ensure_tool_authorized 🔒

execute_call_tool 🔒

init_request_context 🔒

is_shutdown_requested

Checks if shutdown has been requested.

join_error_to_mcp 🔒

Converts a task join error to an MCP internal error.

map_notification_status 🔒

prompt_definition_to_rmcp 🔒

prompt_message_to_rmcp 🔒

record_mcp_metrics 🔒

request_shutdown

Requests a graceful shutdown.

resolve_prompt 🔒

Resolves a prompt by name and arguments into a GetPromptResult.

resource_content_to_rmcp 🔒

resource_definition_to_rmcp 🔒

run_mcp_with_context 🔒

setup_signal_handler

Sets up the signal handler for graceful shutdown (RES-M4).

tool_content_to_rmcp 🔒

tool_definition_to_rmcp 🔒

tool_result_to_rmcp 🔒

Type Aliases

McpResult 🔒