Skip to main content
Create and operate the Fentaris proxy runtime
Use fentaris(...) for new applications. It validates the same proxy options and returns an McpProxy instance that exposes one MCP endpoint and orchestrates upstream MCP servers.

​
Quick Start

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

const proxy = fentaris({
  policy: Policy.allowAll(),
  servers: [
    mcp("filesystem", {
      transport: stdio({
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-filesystem", "./demo-files"],
      }),
    }),
  ],
  port: 4000,
  path: "/mcp",
});

await proxy.start();
Policy.allowAll() is intended for local development and examples. Production proxies should declare least-privilege policy(...) or groups rules because Fentaris denies tool and capability access by default when no explicit allow matches.

​
Options

​
servers

Array of upstream MCP server declarations. 
servers: [
  mcp("github", {
    transport: stdio({ command: "github-mcp-server" }),
  }),
]

​
port

Default port for start(). When omitted, Fentaris reads port from the nearest project fentaris.json, searching upward from the process current working directory. 
port: 4000

​
path

HTTP path for MCP requests. When omitted, Fentaris reads path from the nearest project fentaris.json, then falls back to /mcp. 
path: "/mcp"
Default: /mcp when no project config is found

​
user

Static user context or resolver function. 
user: (req) => ({
  id: req.headers["x-user-id"] as string | undefined,
  tenantId: req.headers["x-tenant-id"],
})

​
identity

Identity strategy configuration for proxy-edge auth.

​
policy and groups

Policy and group declarations used to decide which upstream tools, resources, prompts, and completions are visible to each subject. You can also declare policies and groups after construction with proxy.policy(...) and proxy.group(...). See App-level governance. When no global policy, group policy, or explicit allow-all development policy is configured, tool calls and policy-governed capabilities are denied. Explicit deny rules win over allows from other matching groups.

​
Runtime server registration

Policies can reference upstream MCP server names that are registered later through proxy.server(...) or proxy.mcp(...), as long as registration happens before start() or listen(...). 
const proxy = fentaris({
  groups: [
    group({
      id: "limited",
      users: [user("guest")],
      policy: policy("limited").mcp("github").allow("*"),
    }),
  ],
});

proxy.server("github", {
  transport: stdio({ command: "github-mcp-server" }),
});
At startup, Fentaris validates the final runtime configuration and fails with FENTARIS_CONFIG_POLICY_SERVER_NOT_VISIBLE if a policy still references a missing server. Use validateFentarisConfig(config) when you want a strict static check before composing an app with runtime proxy.server(...) calls.

​
logger, autoLog, and profiler

Runtime logging and profiler configuration.

​
name and version

MCP server identity surfaced to clients during initialization.

​
Methods

​
start(options?, onStarted?)

Start the HTTP server. Optional values override the configured port and path for that start call. 
await proxy.start({ port: 4000, path: "/proxy" });

​
close()

Close the HTTP server and all configured upstream transports.

​
listTools(params?, user?)

Aggregate tool lists across upstream servers and apply Fentaris naming and policy. Fentaris applies policy filtering before hooks see the upstream list and again after onListTools and tools:list:after handlers run. Hook-created synthetic tools must use the normal <server>__<tool> name and be covered by policy, or they are removed from the final response.

​
callTool(params, user?)

Call a proxied tool. Fentaris dispatches middleware and hooks, then forwards to the upstream server. Policy deny decisions are terminal: denied calls return a policy error before call hooks, middleware, routes, or upstream dispatch run. Rate limiters attached to the matching policy permission are enforced automatically before forwarding; manual rate-limit middleware is only needed for custom limits outside policy.

​
listResources(params?, user?)

Aggregate resources across upstream servers and rewrite each resource uri to a Fentaris proxy URI.

​
readResource(params, user?)

Parse a Fentaris proxy resource URI, restore the upstream resource URI, and read it from the owning server.

​
listResourceTemplates(params?, user?)

Aggregate resource templates and rewrite each uriTemplate to a Fentaris proxy template URI.

​
listPrompts(params?, user?)

Aggregate prompts and rewrite each prompt name to <server>__<prompt>.

​
getPrompt(params, user?)

Parse a proxied prompt name and retrieve the upstream prompt.

​
complete(params, user?)

Route completion requests for proxied prompt references and proxied resource-template references.

​
local(name)

Register or retrieve a local MCP capability namespace. Repeating the same name returns the same handle so modules can contribute declarations before startup. 
const workspace = app.local("workspace");

workspace.tool("status", { inputSchema: { type: "object" } }, async (ctx) => ({
  content: [{ type: "text", text: ctx.server?.name ?? "workspace" }],
}));

workspace.resource("config://current", { name: "Current config" }, async () => ({
  contents: [{ uri: "config://current", text: "{}" }],
}));

workspace.resourceTemplate("config://projects/{id}", { name: "Project config" }, async (_ctx, params) => ({
  contents: [{ uri: params.uri, text: "project" }],
}));

workspace.prompt("review_pr", { arguments: [{ name: "diff" }] }, async () => ({
  messages: [],
}));

workspace.completion({ type: "ref/prompt", name: "review_pr" }, async (_ctx, params) => ({
  completion: { values: [params.argument.value] },
}));
Local tools and prompts are exposed with the existing proxied naming convention, such as workspace__status. Local resources and resource templates are exposed through Fentaris-owned proxy URIs. The namespace name cannot collide with an upstream MCP server name.

​
App-Level Governance

Use proxy.policy(name) and proxy.group(id) when modules contribute governance to one proxy instance or when upstream MCP servers are registered after construction. 
import { fentaris, stdio, user } from "@fentaris/core";

const app = fentaris();

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

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

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

​
server(name, options?)

Register or retrieve a scoped upstream MCP server handle. server(...) is the app-level alias for mcp(...). 
app.server("filesystem", {
  transport: stdio({
    command: "npx",
    args: ["-y", "@modelcontextprotocol/server-filesystem", "./demo-files"],
  }),
});

​
policy(name)

Register or retrieve a named app-level policy. Repeating the same name returns the same policy instance, so modules can extend one declaration before startup.

​
usePolicy(policyNameOrPolicy)

Apply a named or concrete policy as the global proxy policy after construction. 
app.policy("demo")
  .mcp("github")
  .allow("search_issues");

app.usePolicy("demo");
You can also pass a concrete policy object: 
app.usePolicy(
  policy("demo").mcp("github").allow("search_issues"),
);
app.usePolicy(name) requires the named policy to be declared with app.policy(name) first. When groups are configured, group policies govern matching users; the global policy is used when no groups are configured.

​
group(groupId)

Return a scoped group handle. Chain users(...) and policy(nameOrPolicy) to declare the group before start() or listen(...). 
app.group("maintainers")
  .users(user("alice"))
  .users(user("bob"))
  .policy("maintainers");
Fluent groups must include at least one user and a policy before startup. Named policy references must be declared through app.policy(name) or passed as a concrete policy instance.
Use app.group(id).server(name) to scope middleware, operation handlers, and event handlers to subjects in that group and a visible upstream MCP server. app.group(id).mcp(name) is kept as an equivalent alias. Fentaris validates the final configuration before serving. Common diagnostics include FENTARIS_CONFIG_GROUP_POLICY_UNKNOWN, FENTARIS_CONFIG_GROUP_EMPTY_USERS, FENTARIS_CONFIG_DUPLICATE_GROUP, and FENTARIS_CONFIG_DUPLICATE_POLICY. See Troubleshooting.

​
Routes and Middleware

Use the returned proxy instance for routes, middleware, and hooks: 
proxy.mcp("github").tool("create_issue", async (ctx, next) => {
  if (typeof ctx.args?.title !== "string") {
    return ctx.deny("Issue title is required.");
  }

  return next();
});

​
Low-Level Constructor

The class constructor is available for advanced integrations that need explicit object construction: 
import { McpProxy } from "@fentaris/core";

const proxy = new McpProxy({
  servers,
  port: 4000,
  path: "/mcp",
});
For normal applications, prefer fentaris(...).