Client Configuration

This page covers the technical configuration patterns for connecting Fluent to supported AI clients.

If you want the plain-language explanation first, start here:

• Using Fluent with AI Apps

Today, the documented public path is Fluent OSS. Cloud-specific connection docs will be published when Fluent Cloud is ready.

Scaffold Generator

The scaffold generator is the preferred way to produce MCP client configs. It resolves tokens, constructs URLs, and outputs ready-to-use JSON.

Syntax

npm run scaffold:mcp -- --client <client> --track <track> [options]

Parameters

Parameter	Values	Purpose
--client	claude, codex	Target client
--track	cloud, oss	Deployment track (oss is the documented path today)
--base-url	URL	OSS server address
--token	string	Override bearer token
--root	path	Override Fluent data root
--out	path	Write config to file

Examples

Claude against OSS:

npm run scaffold:mcp -- --client claude --track oss \
  --base-url http://127.0.0.1:8788

Claude against OSS, written to a file:

npm run scaffold:mcp -- --client claude --track oss \
  --base-url http://127.0.0.1:8788 \
  --out ./tmp/fluent-claude.mcp.json

Manual Configuration

Fluent Cloud

Fluent Cloud setup details are not published yet. This page intentionally focuses on self-hosted configuration until the cloud product is ready for public setup documentation.

Self-Host

{
  "mcpServers": {
    "fluent": {
      "url": "http://127.0.0.1:8788/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

Replace <your-token> with the output of npm run oss:token:print.

Behind a Reverse Proxy

If Fluent is behind a reverse proxy with a public domain:

{
  "mcpServers": {
    "fluent": {
      "url": "https://fluent.yourdomain.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

Generate the config with the proxied URL:

npm run scaffold:mcp -- --client codex --track oss \
  --base-url https://fluent.yourdomain.com

Token Resolution

The scaffold generator resolves the OSS bearer token in this order:

1. --token flag (if provided)
2. FLUENT_OSS_TOKEN environment variable
3. ~/.fluent/auth/oss-access-token.json (or custom --root)
4. Legacy FLUENT_LOCAL_TOKEN / ~/.fluent/auth/local-access-token.json

General Patterns

First Call

Always start with fluent_get_capabilities. This returns the contract version, domain state, and tool discovery hints that guide subsequent calls.

Domain Routing

Check readyDomains in the capabilities response:

• If a domain is in readyDomains, route normally
• If a domain is available, enable it and run onboarding
• If a domain is disabled, do not auto-enable it

Tool Discovery

Use the toolDiscovery.groups from capabilities as workflow hints:

• meals_planning -- weekly planning tools
• meals_shopping -- grocery and ordering tools
• health_fitness -- training and coaching tools
• style -- closet and wardrobe tools

The MCP tools/list endpoint is the authoritative full registry.

Reconnecting

After changing the endpoint, rotating the token, or upgrading Fluent:

1. Reconnect the MCP server in your client
2. Re-authorize if prompted
3. Clear stale credentials if the client caches them