Skip to main content
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 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.

​
Validate the Project

Run the local checks before connecting a client: 
fentaris check --offline
Use fentaris doctor --runtime when you want to verify that the running endpoint responds correctly.