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.

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

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

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

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 the runnable proxy example.
• fentaris.json for CLI project discovery and runtime port/path defaults.
• .gitignore, TypeScript config, and package scripts.

The generated dev and start scripts load an optional project .env. The file is ignored by Git. Fentaris creates FENTARIS_AUTH_KEY there only when the first local encrypted credential is written; projects without encrypted credentials do not need a key.

The generated package.json pins @fentaris/core to a caret range that matches the CLI release (currently ^2.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

For a direct curl smoke test, 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":{}}'

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.

Add a Local Edge Device

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

Use fentaris doctor --runtime when you want to verify the MCP endpoint and enabled integrated Edge routes.

Related Documentation

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