Team-governed proxy

Build a runnable proxy with API-key users, groups, policy, upstream servers, local tools, and secrets.

Use this example when a team needs one Fentaris endpoint with separate reader, developer, and maintainer access. It includes a remote upstream MCP server, a stdio upstream MCP server, one local app-owned namespace, API-key identity, group-scoped credentials, and validation commands.

The maintained runnable project is now in Fentaris/team-governed-proxy. See its README for installation and verification, or follow the runnable example walkthrough. This guide shows a broader configuration you can adapt with your own upstreams.

Quick Start

Create the project:

mkdir team-governed-proxy
cd team-governed-proxy
npm init -y
npm i @fentaris/core @fentaris/cli
mkdir -p src .fentaris demo-files
printf '# Team-governed proxy\n' > README.md

Add package scripts:

{
  "type": "module",
  "scripts": {
    "dev": "fentaris dev",
    "check": "fentaris check --offline",
    "doctor": "fentaris doctor"
  },
  "dependencies": {
    "@fentaris/cli": "^1.0.0",
    "@fentaris/core": "^2.0.0"
  },
  "devDependencies": {
    "tsx": "^4.20.0",
    "typescript": "^5.8.0"
  }
}

Create fentaris.json:

{
  "name": "team-governed-proxy",
  "packageManager": "npm",
  "entrypoint": "src/index.ts",
  "port": 4000,
  "path": "/mcp",
  "authDir": ".fentaris"
}

Create tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src"]
}

Create .gitignore:

node_modules/
dist/
.env
.env.*
.fentaris/*
!.fentaris/secrets.manifest.json
.fentaris/build/
*.log

Create src/index.ts:

import {
  bearer,
  credential,
  credentialVault,
  projectVaultIdentityStrategy,
  fentaris,
  group,
  jsonConsoleLogger,
  mcp,
  policy,
  stdio,
  streamableHttp,
  user,
} from "@fentaris/core";

const readerPolicy = policy("reader")
  .mcp("workspace")
  .allow("status")
  .mcp("filesystem")
  .allow("list_directory");

const developerPolicy = policy("developer")
  .mcp("workspace")
  .allow("status")
  .mcp("workspace")
  .allow("deploy_plan")
  .mcp("filesystem")
  .allow("list_directory")
  .mcp("github")
  .allow("search_issues");

const maintainerPolicy = policy("maintainer")
  .mcp("workspace")
  .allow("*")
  .mcp("filesystem")
  .allow("list_directory")
  .mcp("github")
  .allow("search_issues")
  .mcp("github")
  .allow("create_issue");

const app = fentaris({
  logger: jsonConsoleLogger(),
  autoLog: true,
  identity: { strategy: projectVaultIdentityStrategy({ root: process.cwd() }), required: true },
  cli: {
    mcpAccounts: {
      workspace: {
        default: "user:reader",
        allowed: ["user:reader", "user:developer", "user:maintainer"],
      },
      filesystem: {
        default: "user:reader",
        allowed: ["user:reader", "user:developer", "user:maintainer"],
      },
      github: {
        default: "user:developer",
        allowed: ["user:developer", "user:maintainer"],
      },
    },
  },
  groups: [
    group({
      id: "readers",
      users: [user("reader")],
      policy: readerPolicy,
    }),
    group({
      id: "developers",
      users: [user("developer")],
      credentials: {
        "github.token": credentialVault("github.developers.token"),
      },
      policy: developerPolicy,
    }),
    group({
      id: "maintainers",
      users: [user("maintainer")],
      credentials: {
        "github.token": credentialVault("github.maintainers.token"),
      },
      policy: maintainerPolicy,
    }),
  ],
});

app.mcp("filesystem", {
  transport: stdio({
    command: "npx",
    args: ["-y", "@modelcontextprotocol/server-filesystem", "./demo-files"],
  }),
});

app.mcp("github", {
  transport: streamableHttp({ url: "https://github.example/mcp" }),
  auth: bearer(credential("github.token")),
});

app.local("workspace")
  .tool("status", { inputSchema: { type: "object" } }, (ctx) => ({
    content: [
      {
        type: "text",
        text: `subject=${ctx.subject?.id ?? "anonymous"}`,
      },
    ],
  }))
  .tool("deploy_plan", { inputSchema: { type: "object" } }, () => ({
    content: [{ type: "text", text: "manual approval required before deploy" }],
  }));

app.use((ctx, next) => {
  ctx.log.setTag("subject", ctx.subject?.id ?? "anonymous");
  ctx.log.setTag("groups", ctx.subject?.groups.map((group) => group.id).join(",") ?? "");
  return next();
});

await app.start();

Secrets Manifest

Create the manifest after the entrypoint exists:

fentaris secrets manifest

See project vault unlocking and migration. macOS can use Keychain instead of an explicit unlock key. Group policies remain distinct from upstream account aliases.

The generated .fentaris/secrets.manifest.json is a schema file, not a secret store. Its exact entries depend on the credential helpers in the entrypoint. It uses this shape:

{
  "version": 1,
  "references": [
    {
      "ref": "github.token",
      "scope": "group:developers",
      "source": { "type": "vault", "reference": "github.developers.token" }
    }
  ]
}

Commit the generated manifest. Do not commit .fentaris/vault.json, raw API keys, upstream tokens, or FENTARIS_VAULT_KEY.

Provision Local Credentials

Generate API keys and store upstream credentials:

export FENTARIS_VAULT_KEY="<explicit-vault-unlock-key>"

fentaris auth keys create --user reader --name workstation
fentaris auth keys create --user developer --name workstation
fentaris auth keys create --user maintainer --name workstation

printf '%s' "$DEVELOPER_GITHUB_TOKEN" \
  | fentaris secrets set github.developers.token --stdin --non-interactive
printf '%s' "$MAINTAINER_GITHUB_TOKEN" \
  | fentaris secrets set github.maintainers.token --stdin --non-interactive

Save each generated API key when it is printed. Fentaris stores only hashes in the encrypted local credential store.

Validate The Project

Run local checks before connecting a client:

npm run check
npm run doctor
fentaris secrets manifest --check
fentaris secrets doctor

Expected successful shapes:

fentaris check --offline
ok  Project config is valid
ok  Entrypoint was found
ok  Policy does not use development-only allowAll()

fentaris secrets doctor
ok  Required secrets are present
ok  Secrets manifest is current
ok  Sensitive credential files are not tracked

Start the proxy:

npm run dev

In another shell, inspect administrative connections and verify runtime health:

export FENTARIS_VAULT_KEY="<explicit-vault-unlock-key>"
export FENTARIS_API_KEY="<reader-api-key>"

fentaris doctor --runtime
fentaris mcp
fentaris mcp tools github --json

MCP inventory lists configured upstreams independently of the incoming user. Test reader and maintainer policies through the running MCP endpoint using their respective API keys. The reader’s tools/list should include filesystem list access and omit maintainer-only GitHub writes; a denied tool call must fail before upstream dispatch. Administrative tool discovery does not establish a client’s runtime permissions.

MCP Client Test

For a direct JSON-RPC smoke test, call the running MCP endpoint with the API key header:

curl -s http://localhost:4000/mcp \
  -H 'content-type: application/json' \
  -H "x-fentaris-api-key: $FENTARIS_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Expected shape:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "workspace__status"
      }
    ]
  }
}

Related Documentation

• Agent implementation guide
• Governance auth
• CLI Usage
• Troubleshooting