Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
4.0 KB
Raw Blame

How to: add an MCP server (connector)

MCP servers give agents tools. evenfire never “auto-discovers the whole cluster”: a Context allowlists which servers a Host may reach, and the platform enforces that with NetworkPolicies on Kubernetes.

Option A — mcp-host dev mode (contributors, no cluster)

When running mcp-host standalone (CLERUM_DEV_MODE=true CLERUM_ENABLE_AUTH=false npm run dev; see Dev mode), wire servers with CLERUM_MCP_SERVERS (JSON array). Each entry needs name, contextRef, transport, enabled, and status.ready: true, or it is skipped as not ready (mcp-host checks only ready; deployed in the example is not read):

CLERUM_MCP_SERVERS=[{"name":"my-mcp","contextRef":"dev-context","transport":{"type":"streamableHttp","url":"http://my-mcp:3000/mcp"},"enabled":true,"status":{"deployed":true,"ready":true}}]

Restart the dev process after changing env. There is no NetworkPolicy isolation in dev mode — this is for local tool smoke tests only.

Option B — Kubernetes (platform path)

1. Declare the server

apiVersion: clerum.io/v1alpha1
kind: McpServer
metadata:
  name: mongodb-server
  namespace: mcp-server
spec:
  # image, transport (HTTP or stdio), env, auth, egress — see CRD reference

Full schema: McpServer CRD.
Examples: charts/clerum-crds/examples/.

2. Allow it on a Context

apiVersion: clerum.io/v1alpha1
kind: Context
metadata:
  name: context1
  namespace: mcp-server
spec:
  contextId: context1
  mcpServers:
    - mongodb-server

Anything not listed is unreachable to hosts that use this context.

3. Point a Host at the Context

apiVersion: clerum.io/v1alpha1
kind: Host
metadata:
  name: chatllm
  namespace: mcp-host
spec:
  host: chatLLM
  contextRef: context1
  secretRef: chatllm-api-keys
  model:
    provider: openai
    name: gpt-5.4-mini

4. Apply and verify

kubectl apply -f your-mcpserver.yaml -f your-context.yaml
# host-context-controller reconciles Deployments, Services, NetworkPolicies

Check:

  • McpServer / Deployment ready in the MCP namespace
  • mcp-host discovery / tool list includes the new tools
  • First tool call respects approval policy

Option C — the Control UI

Installed Connectors (/connectors) → Create builds the same McpServer resource as Option B, through a guided form (identity, transport/runtime, secrets) plus an EgressEditor step for the egress policy: closed-by-default, with private, metadata, link-local, and reserved IPv4 ranges rejected outright. Both this form and registry installs check the connector image against an allowlist that is audit-mode by default — the check is a no-op unless an operator turns on enforcement, since the shipped default is off. The audit signal comes later, at reconcile: host-context-controller logs a would-be denial ("audit mode, allowing") for a non-allowlisted image and still builds it, by default. This allowlist is separate from the sha256 digest pinning used for custom coordinator images. See Control UI.

Control UI connectors list at /mcp-servers Dev cluster, demo tenant.

Stdio vs HTTP

  • HTTP / Streamable HTTP — direct service URL
  • stdio — typically via stdio-bridge sidecar translating to HTTP

See stdio-bridge README and mcp-servers.

Security checklist

  • Image pinned by digest in production
  • Secrets referenced key-by-key, not ambient cluster access
  • Egress bindings only as wide as the connector needs
  • Context allowlist reviewed like IAM
  • Approval policy still requires human yes for risky tools

Related