Quickstart

Create a Fentaris project, run the local proxy, and connect an MCP client.

This quickstart uses the Fentaris CLI to generate a ready-to-run local project with one remote HTTP upstream MCP server.

The generated specification upstream requires outbound network access. For a self-contained local-tool example, use Team-governed proxy.

Choose a Setup Path

Setup with an agent

Install the Fentaris agent skills when you want an agent to ask setup questions, choose the project shape, configure upstream MCP servers, and run validation.

Setup with the CLI

Install @fentaris/cli when you want generated files, fentaris.json, package scripts, and a local proxy running at the default endpoint.

Manual setup

Install @fentaris/core directly when you already have a TypeScript project or want full control over the proxy declaration.

CLI Setup

Install the CLI and generate a project:

npm i -g @fentaris/cli

fentaris init my-proxy
cd my-proxy
fentaris dev

local is the default boilerplate. Choose the small team-ready variant when you want API-key identity and a fail-closed tool allow-list:

fentaris init team-proxy --template team

Both templates export their editable configuration from src/index.ts; importing it for fentaris mcp tools does not start the proxy. The team README explains how to create its client API key manually with fentaris auth keys create.

For automation, pass the project name and scaffold choices explicitly:

fentaris init my-proxy --non-interactive --package-manager pnpm --skip-install --skip-git
cd my-proxy
pnpm install

If you omit --skip-install, the package manager passed to --package-manager must be installed and available on PATH.

The proxy listens on http://localhost:4000/mcp by default. Generated projects read port and path from fentaris.json, so fentaris dev and app.start() stay aligned without hardcoding the endpoint in src/index.ts.

The generated app explicitly allows all upstream operations and does not configure authentication. Replace the development policy with API-key auth and an allow-list policy before exposing the proxy outside your machine.

Generated Project

fentaris init creates these files:

• src/index.ts with inspectable proxy configuration and guarded startup.
• fentaris.json for CLI project discovery and runtime port/path defaults.
• .gitignore, TypeScript config, and package scripts.

The generated dev watcher and start scripts load an optional project .env. The file is ignored by Git. Project vaults use macOS Keychain or an explicitly configured FENTARIS_VAULT_KEY/credential-store adapter. Fentaris never generates an unlock key into .env; environment-only bindings do not require a vault key.

The generated package.json pins @fentaris/core to a caret range that matches the CLI release (currently ^3.0.0). This makes local SDK/CLI integration tests deterministic — the app installs the same core the CLI was validated against instead of whatever happens to be latest on npm.

fentaris init initializes a git repository when git is available. Pass --skip-git to create only the project files.

Local development against the monorepo

If you are working inside the Fentaris repository and want a generated project to import the local @fentaris/core instead of the pinned range, pass a workspace or file reference to --core-version:

fentaris init my-proxy --core-version workspace:*

or

fentaris init my-proxy --core-version file:../packages/core

The doctor check skips installed-version validation for workspace and file references. Use your package manager to update released dependencies:

pnpm update @fentaris/core

Connect a Client

Point your MCP client to the endpoint printed by fentaris dev, usually:

http://localhost:4000/mcp

Leave fentaris dev running. In a second terminal, initialize the MCP session and save the response headers:

curl -sS -D headers.txt -o initialize.json -X POST http://127.0.0.1:4000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'

Capture the mcp-session-id header from the initialize response:

SESSION_ID="$(grep -i '^mcp-session-id:' headers.txt | tr -d '\r' | cut -d' ' -f2)"

Send the MCP initialized notification on the same session:

curl -sS -X POST http://127.0.0.1:4000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "mcp-session-id: $SESSION_ID" \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

Then list tools with the same mcp-session-id header:

curl -sS -X POST http://127.0.0.1:4000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "mcp-session-id: $SESSION_ID" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

Call the First Tool

Call one tool returned by tools/list on the same session:

curl -sS -X POST http://127.0.0.1:4000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "mcp-session-id: $SESSION_ID" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"specification__search","arguments":{"query":"accessibility","limit":1}}}'

The result should contain a successful MCP tool response. If specification__search is absent, verify outbound access to the generated upstream and rerun tools/list.

You can also use npx @modelcontextprotocol/inspector and point it at http://127.0.0.1:4000/mcp.

For client-specific JSON snippets, see Client Configs.

Replace the Development Policy

The generated Policy.allowAll() is only for the first local run. Replace the import and fentaris(...) declaration in src/index.ts with an explicit allow-list before sharing the proxy:

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

const app = fentaris({
  policy: policy("quickstart")
    .mcp("specification")
    .allow("search"),
});

Keep the generated app.mcp("specification", ...) block, restart fentaris dev, and initialize a new MCP session. tools/list should now expose only specification__search; a direct call to another specification__* tool should return not-permitted.

Add a Local Edge Device

Edge is an alpha/preview surface. Validate service lifecycle and recovery on every target operating system before rollout. Protocol, CLI, and local state formats may change before a stable release, and the local control-plane mode is not a production multi-instance deployment.

Enable the disabled-by-default edge.controlPlane block in fentaris.json, set publicOrigin to http://127.0.0.1:4000, and restart the app. In one terminal join the device:

npx @fentaris/edge join http://127.0.0.1:4000/_fentaris/edge --name "My laptop"

In the project terminal approve the displayed code for an application subject:

fentaris edge approve ABCD-EFGH --subject alice

The running app enrolls the device, derives its assignments from your Edge targets and placements, and publishes capabilities after local setup and readiness succeed. See Set Up an Edge Device for workload declarations and production guidance.

Validate the Project

Run the local checks before connecting a client:

fentaris check --offline

With fentaris dev still running, verify the full runtime from the second terminal:

fentaris doctor --runtime

The final runtime check should report that MCP initialize responded at the configured endpoint. If it fails, follow the printed hint and Troubleshooting before connecting a client.

Related Documentation

• CLI Reference
• Client Configs
• Config file
• Environment variables
• Troubleshooting