Config File

Generated projects use fentaris.json at the project root. The CLI uses this file to discover the project, run scripts, validate local state, and build runtime metadata. When an app starts without explicit port or path options, @fentaris/core also searches upward from the current working directory and uses the nearest project config defaults. SDK-only projects do not need fentaris.json for local auth and secrets commands. When fentaris auth or fentaris secrets cannot find a project config file, it can discover the nearest package.json that depends on @fentaris/core and use optional package.json metadata for the entrypoint and local runtime directory.

Quick Start

{
  "name": "my-proxy",
  "packageManager": "pnpm",
  "entrypoint": "src/index.ts",
  "port": 4000,
  "path": "/mcp",
  "authDir": ".fentaris",
  "edge": {
    "controlPlane": {
      "enabled": false,
      "mode": "local",
      "stateDir": "edge-control-plane"
    }
  }
}

Fields

`name`

Project name used in generated metadata and CLI output.

"name": "my-proxy"

`packageManager`

Package manager used for generated scripts. During fentaris init, the selected binary is also used for dependency installation unless --skip-install is passed.

"packageManager": "pnpm"

Allowed values:

pnpm
npm
bun

`entrypoint`

Runtime entrypoint copied into build metadata.

"entrypoint": "src/index.ts"

The file must exist for project health checks to pass. Tool discovery imports this module and reads its fentarisConfig, config, or default export. Generated entrypoints export the configuration and start the listener only when executed directly.

`port`

Local port printed by fentaris dev, used by runtime checks, and used by app.start() when the app does not pass an explicit port.

"port": 4000

`path`

MCP endpoint path served by the generated proxy. app.start() uses this path when the app does not pass an explicit path.

"path": "/mcp"

The default local endpoint is http://localhost:4000/mcp.

`authDir`

Directory for local encrypted credentials and CLI auth state.

"authDir": ".fentaris"

Generated projects include .gitignore entries for .fentaris/ because it contains local credentials, upstream OAuth tokens, and build output. The committed .fentaris/secrets.manifest.json schema is not ignored.

`secrets`

Optional secrets provider settings. Generated projects default to the local encrypted store.

"secrets": {
  "provider": "local"
}

`fentaris`

Optional Fentaris Cloud project metadata for forward-compatible cloud sync. Cloud sync is not available yet; keep using the local encrypted store.

"fentaris": {
  "projectId": "proj_123",
  "environment": "production"
}

SDK-Only Auth and Secrets Metadata

SDK-only projects can configure fentaris auth and fentaris secrets without creating fentaris.json:

{
  "dependencies": {
    "@fentaris/core": "^3.0.0"
  },
  "fentaris": {
    "entrypoint": "src/server.ts",
    "authDir": ".fentaris"
  }
}

Supported fields:

entrypoint - TypeScript file scanned by fentaris secrets manifest.
authDir - local runtime directory for secrets.manifest.json and credentials.enc.json, used by both auth and secrets commands.
port, host, and path - optional defaults used by the synthetic secrets project model.

If entrypoint is omitted, fentaris secrets manifest checks src/index.ts, src/main.ts, and index.ts. Pass --entrypoint <path> when the file uses another name.

Application Config: control plane and legacy CLI metadata

The legacy AgentToolDiscoveryService library reads cli.mcpAccounts for downstream policy-filtered discovery. Administrative MCP commands use named upstream declarations and do not accept --as.

`edge.controlPlane`

The integrated device authority, enrollment routes, WebSocket gateway, planner, and reconciler are disabled by default. A minimal local development configuration is:

{
  "edge": {
    "controlPlane": {
      "enabled": true,
      "mode": "local",
      "publicOrigin": "http://127.0.0.1:4000",
      "basePath": "/_fentaris/edge",
      "stateDir": "edge-control-plane"
    }
  }
}

publicOrigin is the canonical origin used to generate enrollment and gateway URLs. Non-loopback origins must use HTTPS. basePath must not overlap the MCP path. stateDir is resolved beneath authDir and must not escape it. Serializable configuration accepts only safe scalar fields. Approval callbacks, assignment resolvers, managed stores, and authorization services are TypeScript-only McpProxyOptions.edge.controlPlane adapters. Managed mode fails startup unless every required durable adapter is present. The separate edge.control option enables agent-native inventory and explicit orchestration tools. It is independent from the integrated connection control plane and remains an explicit policy-governed opt-in. See Edge API Reference.

Application Config: named MCP accounts

import { defineFentarisConfig, mcp, oauth, bearer, credential, policy, streamableHttp } from "@fentaris/core";

export default defineFentarisConfig({
  servers: [
    mcp("gmail", {
      description: "Mail tools",
      transport: streamableHttp({ url: "https://mail.example.com/mcp" }),
      accounts: {
        gabry848: { auth: oauth(), allowedUsers: ["assistant"] },
        gino: { auth: oauth() },
      },
    }),
    mcp("github", {
      transport: streamableHttp({ url: "https://github.example.com/mcp" }),
      accounts: { work: { auth: bearer(credential("github.work.token")) } },
    }),
  ],
  policy: policy("default").mcp("gmail").allow("*"),
});

accounts maps stable local aliases to optional auth, env, transport, allowedUsers, and inspectIdentity declarations. Account settings inherit server settings. auth: { type: "none" } explicitly disables inherited authentication; { type: "managed" } describes authentication performed inside an upstream server. Transport credential bundles use environment credential references. Account aliases contain letters, numbers, dots, underscores, and hyphens. inspectIdentity is an optional async provider lookup returning { identity?: Record<string, string>, permissions?: string[] }. Live discovery calls it only after successful tool discovery. Offline reads never call it; failure leaves identity unavailable without dropping tools. Without an accounts declaration, administrative inventory shows one default connection. Runtime preserves legacy scoped authentication until an explicit connect/migration creates that default account’s binding. An explicit empty accounts object is invalid for inventory. Runtime requests use UserContext.upstreamAccounts, for example { id: "assistant", upstreamAccounts: { gmail: "gabry848" } }. Multiple accounts require an explicit selection; runtime never picks the first. allowedUsers adds connection restrictions to existing policy checks and never grants tool access. Legacy cli.mcpAccounts remains a contract of the policy-filtered AgentToolDiscoveryService library. Its default and allowed values are downstream user:<id> / group:<id> selectors. Administrative MCP inventory does not use this mapping, and no migration interprets those selectors as upstream account aliases.

Application Config: `oauth`

Proxy-level wiring for upstream servers declared with oauth(). Set it on the app config, not in fentaris.json.

fentaris({
  servers: [mcp("linear", { transport: streamableHttp({ url }), auth: oauth() })],
  oauth: { publicUrl: "https://proxy.example.com", consentTimeoutMs: 90_000 },
});

`oauth.publicUrl`

Externally reachable base URL used to build the redirect callback. Required behind a reverse proxy or a non-loopback host. Must be an absolute http or https URL.

`oauth.callbackPath`

Path of the hosted redirect route. Defaults to /_fentaris/oauth/callback. Must not overlap the MCP path or the Edge control-plane base path.

`oauth.store`

Token store implementing get, set, delete, and list. Defaults to the encrypted local store when a key is available, otherwise an in-memory store.

`oauth.authDir`

Directory of the encrypted local token store. Defaults to .fentaris.

`oauth.consentTimeoutMs`

How long a tool call waits for consent before returning a pending result. Defaults to 90000.

`oauth.pendingTtlMs`

How long an unfinished authorization stays valid. Defaults to 600000.

`oauth.agentTools`

Set to false to skip the built-in fentaris__auth_status and fentaris__auth_login tools. Defaults to true when an interactive OAuth server is declared.

See Upstream OAuth 2.1 for the declaration forms and the consent flow.

Legacy Filename

The CLI can still discover fentaris.config.json, but generated projects use fentaris.json.

mv fentaris.config.json fentaris.json

Home

Documentation

Quick Start

Fields

`name`

`packageManager`

`entrypoint`

`port`

`path`

`authDir`

`secrets`

`fentaris`

SDK-Only Auth and Secrets Metadata

Application Config: control plane and legacy CLI metadata

`edge.controlPlane`

Application Config: named MCP accounts

Application Config: `oauth`

`oauth.publicUrl`

`oauth.callbackPath`

`oauth.store`

`oauth.authDir`

`oauth.consentTimeoutMs`

`oauth.pendingTtlMs`

`oauth.agentTools`

Legacy Filename

​Quick Start

​Fields

​name

​packageManager

​entrypoint

​port

​path

​authDir

​secrets

​fentaris

​SDK-Only Auth and Secrets Metadata

​Application Config: control plane and legacy CLI metadata

​edge.controlPlane

​Application Config: named MCP accounts

​Application Config: oauth

​oauth.publicUrl

​oauth.callbackPath

​oauth.store

​oauth.authDir

​oauth.consentTimeoutMs

​oauth.pendingTtlMs

​oauth.agentTools

​Legacy Filename

​Related Documentation

Quick Start

Fields

`name`

`packageManager`

`entrypoint`

`port`

`path`

`authDir`

`secrets`

`fentaris`

SDK-Only Auth and Secrets Metadata

Application Config: control plane and legacy CLI metadata

`edge.controlPlane`

Application Config: named MCP accounts

Application Config: `oauth`

`oauth.publicUrl`

`oauth.callbackPath`

`oauth.store`

`oauth.authDir`

`oauth.consentTimeoutMs`

`oauth.pendingTtlMs`

`oauth.agentTools`

Legacy Filename

Related Documentation