Security

Security practices and patterns for Fentaris proxies.

Keep Fentaris deployments safe with centralized identity, policy, secrets, and audit controls.

Start with allow-list policy, authenticated users, scoped upstream servers, and structured logging. Add runtime middleware only for checks that depend on request data.

Quick Start

Declare the proxy with high-level helpers and keep security rules close to the upstream MCP server they govern.

import { fentaris, group, mcp, policy, stdio, user } from "@fentaris/core";

const productionPolicy = policy("production")
  .mcp("filesystem")
  .allow("read_file")
  .mcp("filesystem")
  .deny("write_file")
  .mcp("filesystem")
  .deny("delete_file");

const proxy = fentaris({
  groups: [
    group({
      id: "readers",
      users: [user("alice", { tenantId: "acme" })],
      policy: productionPolicy,
    }),
  ],
  servers: [
    mcp("filesystem", {
      transport: stdio({
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-filesystem", "/srv/shared"],
      }),
    }),
  ],
  autoLog: true,
});

Use allow-list policy in production. Deny rules are useful for explicit exceptions, but the baseline should be the smallest set of tools and capabilities each group needs.

Guard Destructive Tools

Policy should block known destructive tools before runtime middleware runs.

const supportPolicy = policy("support")
  .mcp("github")
  .allow("search_issues")
  .mcp("github")
  .allow("create_issue")
  .mcp("github")
  .deny("delete_repo");

Add middleware when the decision depends on request arguments, tenant state, or a live approval system.

proxy.mcp("github").tool("create_issue", async (ctx, next) => {
  if (typeof ctx.args?.title !== "string") {
    return ctx.deny("Issue title is required.");
  }

  ctx.log.info("github.create_issue.validated", {
    subject: ctx.subject?.id,
    groups: ctx.subject?.groups.map((group) => group.id),
  });

  return next();
});

Govern All MCP Capabilities

Tools are only one MCP surface. Resources, resource templates, prompts, and completion can expose data or shape model behavior.

const leastPrivilege = policy("least-privilege")
  .mcp("filesystem")
  .allow("read_file")
  .mcp("filesystem")
  .allowCapability({
    operation: "resources:list",
    targetKind: "resource",
  })
  .mcp("filesystem")
  .denyCapability({
    operation: "resource:read",
    target: "file:///secrets.env",
    targetKind: "resource",
  });

Use list permissions for discovery and direct-operation permissions such as resource:read, prompt:get, and completion:complete before Fentaris forwards a request upstream.

Scope Servers Per Group

Use groups to make server access explicit. This keeps tool visibility, credentials, and policy tied to the caller.

const proxy = fentaris({
  groups: [
    group({
      id: "support",
      users: [user("alice")],
      servers: [
        mcp("github", {
          transport: stdio({ command: "github-mcp-server" }),
        }),
      ],
      policy: policy("support")
        .mcp("github")
        .allow("search_issues")
        .mcp("github")
        .allow("create_issue"),
    }),
  ],
});

Server-scoped policy also reduces accidental exposure when a new upstream MCP server is added to the proxy.

Compose App-Level Policy And Groups

For incremental proxy setup, declare policies and groups from the app handle before start().

import { fentaris, stdio, user } from "@fentaris/core";

const app = fentaris({ autoLog: true });

app.policy("readonly")
  .mcp("github")
  .allow("search_issues");

app.policy("maintainers")
  .mcp("github")
  .allow("*")
  .mcp("github")
  .deny("delete_repo");

app.group("guests")
  .users(user("guest"))
  .policy("readonly");

app.group("maintainers")
  .users(user("alice"), user("bob"))
  .policy("maintainers");

app.mcp("github", {
  transport: stdio({ command: "github-mcp-server" }),
});

Fentaris validates the final app before serving. Missing named policies, empty groups, duplicate declarations, and policies that still reference missing upstream MCP servers fail startup with configuration diagnostics.

Protect Secrets

Bind secrets through credentials or environment injection. Do not pass secrets through user-controlled metadata or tool arguments.

import { bearer, credential, credentialEnv, fentaris, group, mcp, policy, streamableHttp, user } from "@fentaris/core";

const proxy = fentaris({
  groups: [
    group({
      id: "maintainers",
      users: [user("bob")],
      credentials: {
        "github.token": credentialEnv("GITHUB_TOKEN"),
      },
      policy: policy("maintainers").mcp("github").allow("*"),
    }),
  ],
  servers: [
    mcp("github", {
      transport: streamableHttp({ url: "https://github.example/mcp" }),
      auth: bearer(credential("github.token")),
    }),
  ],
});

Store production secrets in your infrastructure secret manager and inject them at deploy time. Keep .fentaris/credentials.enc.json private when using local encrypted credentials.

Do not forward whole environment maps into HTTP headers. Use auth, resolveHeaders, or an explicit envHeaderMap so token-like variables such as GITHUB_TOKEN are not sent upstream unless you map them deliberately.

Validate Identity

When users declare API keys, Fentaris uses API-key identity by default with the x-fentaris-api-key header. Store API keys as credential sources, such as environment variables or encrypted local credentials, instead of literal strings in code.

For named incoming keys, configure projectVaultIdentityStrategy({root: process.cwd()}) and create a client key:

fentaris auth keys create --user alice --name workstation

import { credentialEnv, fentaris, group, mcp, policy, stdio, user } from "@fentaris/core";

const proxy = fentaris({
  groups: [
    group({
      id: "admins",
      users: [
        user("alice", {
          apiKeys: [credentialEnv("ADMIN_API_KEY")],
        }),
      ],
      policy: policy("admins").mcp("*").allow("*"),
    }),
  ],
  servers: [
    mcp("admin", {
      transport: stdio({ command: "admin-mcp-server" }),
    }),
  ],
});

Trusted identity headers should only be used behind an internal gateway that already authenticated the caller. Do not expose direct user-id headers to untrusted clients.

Audit Decisions

Enable autoLog and add stable tags for traceability. Logs should include metadata, not raw payloads or secret values.

const proxy = fentaris({
  servers: [
    mcp("github", {
      transport: stdio({ command: "github-mcp-server" }),
    }),
  ],
  autoLog: true,
});

proxy.use(async (ctx, next) => {
  ctx.log.setTag("subject", ctx.subject?.id ?? "anonymous");
  ctx.log.setTag("tenant", String(ctx.subject?.tenant?.id ?? "unknown"));
  return next();
});

Review denied calls regularly. They show missing policy, unexpected client behavior, or attempted abuse.

Govern Edge Orchestration

Keep Edge Control disabled unless an agent needs inventory or explicit orchestration. When enabled, grant edge__list, edge__get, edge__select, edge__call, and edge__call_many independently.

For high-impact fan-out, configure aggregate approval against the exact resolved public-device scope, bounded argument summary, failure policy, concurrency, and deadline. Every child still re-enters normal tool policy and local recipe, grant, and executable consent checks after aggregate approval.

Treat device descriptions, tags, observed facts, and MCP child output as untrusted data. Do not accept route, device, correlation, or status fields from device output. Keep device credentials, opaque node IDs, private paths, grant references, secrets, and complete environments out of agent-visible results and telemetry.

Use durable multi-instance adapters in production. Atomic inventory versions, monotonic connection generations, sticky/round-robin coordination, atomic result consumption, bounded expiry, and idempotent terminal correlation are security boundaries, not only availability optimizations.

Protect the integrated Edge authority

Treat .fentaris/edge-control-plane as credential-bearing authority state. Keep the directory and files owner-only, exclude them from version control and backups that lack equivalent encryption, and set FENTARIS_AUTH_KEY from a secret provider. Approval must use fentaris edge approve; never edit authority JSON directly.

Set an explicit HTTPS publicOrigin behind the trusted TLS terminator. Fentaris ignores hostile Host and forwarded headers when generating join and gateway URLs. Keep the reserved Edge route separate from the MCP path, restrict operator socket access to the application owner, and rotate credentials after suspected disclosure.

Local mode is rejected for unsafe multi-instance use. Production replicas need managed adapters with tenant isolation, compare-and-swap desired assignments, monotonic connection generations, durable revocation, and consistent authorization services. Adapter errors fail closed: they must never broaden eligibility or dispatch.

Harden Network Exposure

Run public Fentaris deployments behind a reverse proxy or cloud load balancer.

• Terminate TLS at the edge and forward only HTTPS traffic.
• Restrict inbound access with private networks or IP allow-lists.
• Keep upstream MCP servers private when possible.
• Rotate API keys and upstream credentials regularly.

Low-Level API

The class constructors remain available for compatibility and advanced embedding. Prefer fentaris(...), mcp(...), stdio(...), streamableHttp(...), group(...), user(...), and policy(...) for new applications.

import { McpProxy, Policy } from "@fentaris/core";

const legacyPolicy = new Policy({ name: "legacy" })
  .mcp("filesystem")
  .allow("read_file");

const proxy = new McpProxy({
  policy: legacyPolicy,
  servers: [filesystemServer],
});

Inbound OAuth

Set oauthIdentityStrategy with an exact issuer and externally visible resource audience. Use HTTPS outside loopback. Fentaris verifies asymmetric JWT signatures, expiry and optional nbf with 60 seconds of skew, and every required scope. It rejects unverified tokens without exposing verifier errors in responses.

verify is the trust boundary for opaque tokens: authenticate introspection calls, require an active token, use a bounded timeout, and return issuer, audience and expiry claims. Fentaris applies the same claim checks afterward. Sessions remain bound to the resolved user and identity strategy.

Fentaris serves protected resource metadata, while authorization, token issuance and client registration remain on the configured issuer. See OAuth 2.1 for JWKS caching and reverse-proxy configuration.

Related Documentation

• Governance auth
• Multi-server routing
• Observability