Tutorial

Build a multi-server proxy step by step with the modern Fentaris app API.

This tutorial starts from a generated Fentaris project and turns it into a proxy for two upstream MCP servers. The app code keeps runtime endpoint settings in fentaris.json and declares upstream servers with app.mcp(...).

Quick Start

Use the optional agent skills when you want an agent to ask setup questions, choose upstream MCP servers, and validate the project after edits:

npx skills add Fentaris/fentaris-skills --skill '*'

Then restart or reload your agent and ask it to use the setup skill:

Use $fentaris-project-setup to help me create a Fentaris proxy for my team.

If you prefer to build the tutorial manually, create a project with the CLI:

npm i -g @fentaris/cli
fentaris init tutorial-proxy
cd tutorial-proxy

Step 1: Configure the Runtime Endpoint

fentaris init writes fentaris.json. Keep endpoint settings there instead of hardcoding them in src/index.ts:

{
  "name": "tutorial-proxy",
  "packageManager": "pnpm",
  "entrypoint": "src/index.ts",
  "port": 4000,
  "host": "127.0.0.1",
  "path": "/mcp",
  "authDir": ".fentaris"
}

When app.start() runs without explicit options, @fentaris/core searches upward from the current working directory and reads the nearest fentaris.json. With the config above, the local endpoint is http://localhost:4000/mcp.

Change port or path in fentaris.json when the local endpoint needs to move. Keep src/index.ts focused on proxy behavior.

Step 2: Create the App Boundary

Open src/index.ts and start with an empty Fentaris app:

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

const app = fentaris({
  policy: Policy.allowAll(),
});

fentaris() creates the proxy application boundary. Project discovery, host, port, and path come from fentaris.json, while upstream MCP servers are attached with app.mcp(...). Policy.allowAll() keeps this local tutorial focused on routing; replace it with an allow-list policy before sharing the endpoint.

Step 3: Attach the Filesystem Server

Create a local directory that the filesystem MCP server can expose:

mkdir demo-files
echo "hello from Fentaris" > demo-files/readme.txt

Then register the upstream MCP server:

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

app.mcp("filesystem", ...) gives the upstream server a stable Fentaris name. Fentaris uses that name when routing tool calls, applying middleware, logging events, and exposing proxied tool names such as filesystem__read_file.

Step 4: Attach a Remote Server

Add the public MCP specification server as a second upstream:

app.mcp("specification", {
  displayName: "MCP Specification",
  transport: streamableHttp({
    url: "https://mcp.specification.website/mcp",
  }),
});

The specification server requires network access. The filesystem server remains local, so you can still start the proxy and test local routing if the remote server is unavailable.

Step 5: Add Global Middleware

Middleware runs after Fentaris builds request context and before the matching upstream MCP server receives the call:

app.use(async (ctx, next) => {
  ctx.log.info("tool-call", {
    server: ctx.server?.name,
    tool: ctx.tool?.name,
  });

  if (ctx.server?.name === "filesystem" && ctx.tool?.name === "delete_file") {
    return ctx.deny("Filesystem delete is disabled in this environment.");
  }

  return next();
});

Use middleware for runtime checks that depend on request data, tool arguments, tenant state, or an approval workflow. For static allow-list access, use policy rules.

Step 6: Add a Server Hook

Server-scoped handles keep observability close to the upstream MCP server they describe:

app.mcp("specification").on("tool:success", async ({ ctx, durationMs }) => {
  ctx.log.info("specification.tool.success", {
    tool: ctx.tool?.name,
    durationMs,
  });
});

This hook only observes successful tool calls for the specification upstream MCP server. It does not affect filesystem calls and does not replace middleware or policy decisions.

Step 7: Start the Proxy

Finish src/index.ts with app.start():

await app.start();

The complete entrypoint should look like this:

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

const app = fentaris({
  policy: Policy.allowAll(),
});

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

app.mcp("specification", {
  displayName: "MCP Specification",
  transport: streamableHttp({
    url: "https://mcp.specification.website/mcp",
  }),
});

app.use(async (ctx, next) => {
  ctx.log.info("tool-call", {
    server: ctx.server?.name,
    tool: ctx.tool?.name,
  });

  if (ctx.server?.name === "filesystem" && ctx.tool?.name === "delete_file") {
    return ctx.deny("Filesystem delete is disabled in this environment.");
  }

  return next();
});

app.mcp("specification").on("tool:success", async ({ ctx, durationMs }) => {
  ctx.log.info("specification.tool.success", {
    tool: ctx.tool?.name,
    durationMs,
  });
});

await app.start();

Run the proxy:

fentaris dev

Step 8: Connect a Client

Point your MCP client to the endpoint from fentaris.json:

http://localhost:4000/mcp

Fentaris exposes one MCP endpoint and routes each request to the matching upstream MCP server. The client talks to Fentaris; Fentaris starts or connects to upstream MCP servers, applies policy and middleware, forwards allowed calls, and records hooks and logs.

Validate the Project

Run static project checks before sharing the endpoint:

fentaris check --offline

When the proxy is running, verify the runtime endpoint:

fentaris doctor --runtime

The tutorial is suitable for local development. Add authentication and allow-list policies before exposing a Fentaris endpoint outside your machine.

What You Built

You now have:

• one Fentaris endpoint configured by fentaris.json
• two upstream MCP servers declared with app.mcp(...)
• global middleware for logging and request-time denial
• a server-scoped hook for remote upstream observability

Related Documentation

• Agent Skills
• Quickstart
• Config file
• Middleware
• Hooks
• Proxy setup