mTLS Gateway

Secure MCP server access with ECDSA P-256 mutual TLS authentication.

Overview

The mTLS (mutual TLS) gateway requires mutual TLS authentication for connections to the MCP server, ensuring that only authenticated clients can perform remote operations.

plaintext

MCP Agent
  │ (client certificate)
  ▼
mTLS Gateway (TLS 1.3)
  │ (server certificate)
  ▼
Nefia MCP Server

Setup

Initialize the CA and Server Certificate

bash

nefia mtls init --hosts localhost,10.99.0.1

The following are generated:

Root CA: ECDSA P-256, valid for 10 years
Server certificate: Valid for 1 year, with SANs for the specified hosts

Files are saved to <state-dir>:

mtls_ca.crt / mtls_ca.key
mtls_server.crt / mtls_server.key

The configuration file is automatically updated with mcp.mtls.enabled: true.

Issue a Client Certificate

Issue a client certificate for an AI agent or operator:

bash

nefia mtls issue-client --name claude-agent --duration 24h

Flag	Description	Default
`--name`	Client name (set as CN)	(required)
`--duration`	Certificate validity period	`24h`
`--out-dir`	Output directory	`./nefia-client-certs/`

The following files are generated:

<name>.crt — Client certificate
<name>.key — Client private key
ca.crt — CA certificate (for server verification)

Start the MCP Server

bash

nefia mcp serve

When mTLS is enabled, a TLS listener starts on mcp.mtls.listen_addr.

Status Check

bash

nefia mtls status

Displays the CA and server certificate CN, expiration date, SANs, enabled state, and listen address.

Configuration

yaml

mcp:
  mtls:
    enabled: true
    listen_addr: "127.0.0.1:19821"
    ca_cert_file: ""     # Uses the default path in state-dir when empty
    cert_file: ""
    key_file: ""

Security Specifications

Item	Specification
CA algorithm	ECDSA P-256
TLS version	TLS 1.3 only
CA validity period	10 years
Server certificate validity period	1 year
Client certificate default validity period	24 hours
Maximum concurrent connections	50

Certificate Revocation

Revoked certificates are tracked in an internal file-based revocation store located in the Nefia state directory. There is no need to manage CRL files manually.

Revocation checks use a modTime-based cache — the revocation file is only re-read when its modification time changes, avoiding per-handshake file I/O overhead.
Use nefia mtls revoke or the nefia.mtls.revoke MCP tool to revoke a certificate by serial number.

Client Authentication Flow

The client initiates a TLS handshake with a client certificate
The server verifies the client certificate against the CA certificate and checks the internal revocation store
The client name is extracted from tls.ConnectionState().PeerCertificates[0].Subject.CommonName
The certificate serial number is extracted and stored in AgentIdentity.Serial for multi-client identification in audit logs
After successful authentication, MCP request processing begins

MCP Tools

AI agents can manage mTLS certificates programmatically via MCP:

Tool	Description
`nefia.mtls.init`	Initialize the mTLS CA (ECDSA P-256) and generate the server certificate.
`nefia.mtls.issue_client`	Issue a client certificate for an AI agent or operator with configurable TTL.
`nefia.mtls.status`	Check mTLS CA status, server certificate validity, and issued client count.
`nefia.mtls.revoke`	Revoke an issued client certificate by serial number. Revocation is persisted in the internal revocation store.