> ## Documentation Index
> Fetch the complete documentation index at: https://fentaris.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<CardGroup cols={3}>
  <Card title="Setup with an agent" icon="bot" href="/getting-started/codex-skills">
    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.
  </Card>

  <Card title="Setup with the CLI" icon="terminal" href="#cli-setup">
    Install `@fentaris/cli` when you want generated files, `fentaris.json`, package scripts, and a local proxy running at the default endpoint.
  </Card>

  <Card title="Manual setup" icon="code" href="/getting-started/setup">
    Install `@fentaris/core` directly when you already have a TypeScript project or want full control over the proxy declaration.
  </Card>
</CardGroup>

## CLI Setup

Install the CLI and generate a project:

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
npm i -g @fentaris/cli
```

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
fentaris init my-proxy
cd my-proxy
fentaris dev
```

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

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
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`.

<Note>
  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.
</Note>

## 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.

<Note>
  `fentaris init` initializes a git repository when git is available. Pass `--skip-git` to create only the project files.
</Note>

### 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`:

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
fentaris init my-proxy --core-version workspace:*
```

or

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
pnpm update @fentaris/core
```

## Connect a Client

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

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
http://localhost:4000/mcp
```

For a direct curl smoke test, initialize the MCP session and save the response headers:

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
SESSION_ID="$(grep -i '^mcp-session-id:' headers.txt | tr -d '\r' | cut -d' ' -f2)"
```

Send the MCP initialized notification on the same session:

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
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":{}}'
```

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

For client-specific JSON snippets, see [Client Configs](/guides/client-configs).

## Validate the Project

Run the local checks before connecting a client:

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
fentaris check --offline
```

<Tip>
  Use `fentaris doctor --runtime` when you want to verify that the running endpoint responds correctly.
</Tip>

## Related Documentation

* [CLI Reference](/reference/cli)
* [Client Configs](/guides/client-configs)
* [Config file](/reference/config-file)
* [Environment variables](/reference/environment-variables)
* [Troubleshooting](/troubleshooting)