Skip to main content

​
Overview

SMKRV MCP Studio implements multiple layers of security. This document covers the security architecture, configuration, and best practices.

​
Network Architecture

​
Port Exposure

Only the frontend nginx container exposes ports to the host network:
ContainerExposed PortsNetwork
frontend3000, 443Host + frontend-net
backend8000backend-net only
mcp8080backend-net only
agent-mcp8090backend-net only
redis6379backend-net only
Backend, MCP, Agent MCP, and Redis containers are not accessible from outside the Docker network. All external traffic routes through nginx.

​
Docker Network Isolation

NetworkContainersPurpose
frontend-netfrontend, backendNginx-to-backend API proxy
backend-netbackend, mcp, agent-mcp, redisInternal services communication
The frontend container cannot directly reach mcp, agent-mcp, or redis. The MCP and agent-mcp containers cannot reach the internet.

​
Encryption at Rest

​
What Is Encrypted

Sensitive data is encrypted at rest using symmetric encryption:
  • Database connection passwords
  • API tokens (MCP bearer token)
  • DNS provider credentials (for SSL certificate issuance)
  • Sensitive extra_params fields (e.g., BigQuery credentials_json)
  • TOTP 2FA secrets
  • OAuth2 client credentials and introspection secrets
The encryption key is set via the STUDIO_ENCRYPTION_KEY environment variable. See Configuration for key management and rotation.

​
Sensitive Extra Params

Cloud database connections store credentials in the extra_params JSON column. Sensitive fields are selectively encrypted:
DB TypeFieldEncrypted?
BigQuerycredentials_jsonYes
BigQueryproject_id, datasetNo
Snowflakeaccount, warehouse, schema, roleNo
CassandrakeyspaceNo
Supabaseproject_refNo
Sensitive fields are:
  • Encrypted on create/update
  • Decrypted only for connection test, SQL preview, and code generation
  • Masked as •••••• in all API responses and exports

​
Admin Authentication

​
Single-Admin Auth

SMKRV MCP Studio uses a single-admin authentication model:
  1. First-time onboarding — when no admin exists, the app shows a setup screen to create the admin account
  2. Login — all access requires authentication via username/password
  3. Session — secure httpOnly cookie (SameSite=Lax, 24h expiry, Secure flag when SSL enabled)
  4. Password storage — securely hashed (never stored in plaintext)

​
Two-Factor Authentication (TOTP)

Optional TOTP-based 2FA:
  • QR code for provisioning with any authenticator app (Google Authenticator, Authy, 1Password, etc.)
  • TOTP secret is encrypted in the database
  • 10 single-use recovery codes generated on setup
  • Separate rate limiter for 2FA attempts (5 per 15 min)

​
Rate Limiting

Login attempts are rate-limited per IP address:
  • 5 failed attempts within 15 minutes triggers a lockout
  • Lockout lasts until the 15-minute window expires
  • 2FA verification has a separate rate limiter

​
Password Reset

Password reset is only available via Docker CLI: 
docker exec -it smkrv-mcp-studio-backend-1 python -m app.cli reset-password
There is no “forgot password” web flow — this is by design for security.

​
Agent MCP Authentication

​
Temporary Tokens

Short-lived access (15 min to 3 hours) for AI agents. Tokens are securely hashed before storage.

​
OAuth2 Client Credentials

For persistent agent access with automatic token refresh. Client secrets are securely hashed, sessions use sliding window expiry.

​
Service-to-Service Auth

The agent-mcp container communicates with the backend using a shared service token that is only available over the internal Docker network.

​
MCP Authentication

The generated MCP server supports four authentication modes:
ModeDescription
NoneNo authentication — suitable for development
Bearer TokenStatic token authentication
OAuth2 Client CredentialsSelf-contained OAuth2 provider with /oauth/token endpoint
OAuth2 IntrospectionValidates tokens against an external RFC 7662 endpoint
Configure in Settings > Server > Security.

​
Container Security

All containers run as non-root users with the principle of least privilege:
ContainerHardening
backendNon-root user
mcpNon-root, dropped capabilities, read-only filesystem, memory/CPU limits
agent-mcpNon-root, dropped capabilities, read-only filesystem, memory/CPU limits
redisPassword-protected, persistent storage

​
MCP Sandbox

The MCP container runs generated code in a hardened environment with no Linux capabilities, immutable root filesystem, and resource limits.

​
Nginx Security Headers

HeaderValue
X-Frame-OptionsDENY
X-Content-Type-Optionsnosniff
Referrer-Policystrict-origin-when-cross-origin
Permissions-Policycamera=(), microphone=(), geolocation=()
Content-Security-PolicyConfigured per deployment
Strict-Transport-Securitymax-age=31536000; includeSubDomains; preload (SSL only)

​
Self-Hosted Security Checklist

Before deploying to production:

​
Environment Configuration

  • STUDIO_ENCRYPTION_KEY is set to a strong encryption key (not auto-generated)
  • STUDIO_JWT_SECRET is set to a strong random string (not auto-generated)
  • REDIS_PASSWORD is set to a strong, unique password
  • STUDIO_AGENT_SERVICE_TOKEN is set to a strong random token
  • .env file has restricted file permissions (chmod 600 .env)

​
Network

  • Only ports 3000 and/or 443 are exposed to the host
  • Backend, Redis, MCP, and Agent MCP ports are not exposed
  • Firewall rules restrict access to necessary ports only

​
SSL/TLS

  • SSL is enabled for production deployments
  • A valid domain name is configured
  • Let’s Encrypt certificates are issued and auto-renewing
  • HTTP-to-HTTPS redirect is configured

​
Authentication

  • Admin account has a strong password (min 8 chars)
  • 2FA (TOTP) is enabled for the admin account
  • MCP auth token is set if the MCP server is network-accessible
  • Agent tokens use appropriate expiry (max 3 hours)
  • Unused agent tokens and OAuth clients are revoked

​
CORS

  • CORS origins are set to specific domains (no wildcard)
  • Only trusted origins are listed

​
See Also