Registration Trust¶

The registry validates agent identity before accepting registration. Agents present a TLS client certificate, and the registry verifies it against configured trust backends.

How It Works¶

sequenceDiagram
    participant A as Agent
    participant R as Registry
    participant CA as Certificate Authority

    A->>CA: Obtain certificate (file/Vault/SPIRE)
    A->>R: POST /heartbeat (with client cert)
    R->>R: Verify cert chain against trust backend
    R-->>A: 200 OK (registered)

    Note over A,R: Subsequent heartbeats use the same mTLS connection

Credential Providers¶

Agents can obtain TLS certificates from three sources:

File Provider (Default)¶

Reads cert/key from files on disk. Works with cert-manager, static certs, or any PKI that writes PEM files.

export MCP_MESH_TLS_MODE=auto
export MCP_MESH_TLS_CERT=/etc/certs/agent.pem
export MCP_MESH_TLS_KEY=/etc/certs/agent-key.pem
export MCP_MESH_TLS_CA=/etc/certs/ca.pem

Vault Provider¶

Fetches certificates from HashiCorp Vault's PKI secrets engine at agent startup.

export MCP_MESH_TLS_MODE=auto
export MCP_MESH_TLS_PROVIDER=vault
export MCP_MESH_VAULT_ADDR=https://vault.example.com:8200
export MCP_MESH_VAULT_PKI_PATH=pki_int/issue/mesh-agent
export VAULT_TOKEN=s.xxxxx
export MCP_MESH_TLS_CA=/etc/certs/vault-ca.pem

Vault-issued certs include both DNS SANs (agent name) and IP SANs (advertised host) for proper hostname verification.

mesh:
  tls:
    mode: "auto"
    vault:
      enabled: true
      addr: "https://vault.vault-system:8200"
      pkiPath: "pki_int/issue/mesh-agent"
      tokenSecret: "vault-agent-token"
      tokenKey: "token"
    caSecret: "mesh-ca-bundle"

services:
  my-agent:
    environment:
      MCP_MESH_TLS_MODE: "auto"
      MCP_MESH_TLS_PROVIDER: "vault"
      MCP_MESH_VAULT_ADDR: "https://vault:8200"  # use http:// for local dev only
      MCP_MESH_VAULT_PKI_PATH: "pki_int/issue/mesh-agent"
      VAULT_TOKEN: "${VAULT_TOKEN}"
      MCP_MESH_TLS_CA: "/etc/certs/ca.pem"

SPIRE Provider¶

Fetches X.509-SVIDs from the SPIRE agent's Workload API via Unix domain socket.

export MCP_MESH_TLS_MODE=auto
export MCP_MESH_TLS_PROVIDER=spire
export MCP_MESH_SPIRE_SOCKET=/run/spire/agent/sockets/agent.sock

mesh:
  tls:
    mode: "auto"
    spire:
      enabled: true
      socketPath: "/run/spire/agent/sockets/agent.sock"
    caSecret: "spire-ca-bundle"

Credential Security¶

For Vault and SPIRE providers, certificates are handled securely:

• In-memory fetch — PEM content never passes through env vars
• Secure temp files — written with 0600 permissions (owner-only read)
• Directory isolation — created with 0700 permissions, PID-namespaced
• tmpfs on Linux — stored in /dev/shm so private keys never touch physical disk
• Cleanup on shutdown — temp files removed when agent stops

Trust Backends¶

The registry validates agent certificates against one or more trust backends:

Backends can be chained: MCP_MESH_TRUST_BACKEND=spire,k8s-secrets — first match wins.

Entity Management¶

Entities represent organizational CAs whose agents are trusted by the mesh.

# Register an entity CA
meshctl entity register "partner-corp" --ca-cert /path/to/ca.pem

# List trusted entities
meshctl entity list

# Revoke an entity (evicts agents in strict mode)
meshctl entity revoke "partner-corp" --force

# Rotate certificates (triggers re-registration via heartbeat protocol)
meshctl entity rotate