Client Configuration

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

These configs tell an AI app how to reach Fluent. You still use Claude, Codex, OpenClaw, or another assistant directly; Fluent is the MCP server that supplies context and tools underneath.

For the plain-language explanation first, start here:

• Using Fluent with AI Apps

Fluent is in early access and open source. Use managed early access for the hosted path, or run Fluent yourself to inspect, self-host, or build with the open-source runtime.

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.

Client output shapes:

• codex and claude return a standard mcpServers.fluent block
• openclaw returns the native mcp.servers.fluent server object you register in your OpenClaw profile

Generic MCP clients are supported through manual HTTP MCP configuration. They are not a scaffold target today because each host chooses its own config file location and wrapper shape.

Syntax

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

Parameters

Parameter	Values	Purpose
--client	claude, codex, openclaw	Target client
--track	cloud, oss	Implementation track
--base-url	URL	Override the default managed or self-hosted base URL
--token	string	Override bearer token for the open-source runtime
--root	path	Override Fluent data root for token resolution
--out	path	Write config to file

Examples

Codex against the early access endpoint:

npm run scaffold:mcp -- --client codex --track cloud

Claude against a self-hosted runtime:

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

Claude against a self-hosted runtime, 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

OpenClaw against a self-hosted runtime:

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

For OpenClaw, the scaffold generator returns the native mcp.servers.fluent JSON block you register in your OpenClaw profile.

For the published OpenClaw plugin install surface, use fluent-openclaw. The checked-in openclaw-plugin/fluent/ mirror is the helper package fluent-openclaw-oss-helper.

Checked-In Client Bundles

The docs repo now mirrors the client bundle roots referenced throughout these guides:

Client	Bundle root	Key mirrored files
Codex	plugins/fluent/	.codex-plugin/plugin.json, .mcp.json, .mcp.hosted.json, .mcp.oss.json, .mcp.local.json
Claude	claude-plugin/fluent/	.claude-plugin/plugin.json, .mcp.json, .mcp.hosted.json, .mcp.oss.json, .mcp.local.json
OpenClaw	openclaw-plugin/fluent/	Mirrored helper bundle for OpenClaw docs parity: openclaw.plugin.json, helper package.json, index.js, .mcp.json, .mcp.hosted.json, .mcp.oss.json, .mcp.local.json

Manual Configuration

Early Access Endpoint

This config points at Fluent's managed MCP endpoint and relies on the client's authorization flow rather than a bearer token. Use it when you have managed early access or a provisioned setup:

{
  "mcpServers": {
    "fluent": {
      "type": "http",
      "url": "https://mcp.meetfluent.app/mcp"
    }
  }
}

Reconnects may require a fresh authorization if the client cached an older registration. Fluent expects these scopes on the active grant:

• meals:read
• meals:write
• health:read
• health:write
• style:read
• style:write
• offline_access

Self-Host

{
  "mcpServers": {
    "fluent": {
      "type": "http",
      "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.

Use the same endpoint and bearer-token pattern for generic MCP clients that accept a standard HTTP MCP server block.

OpenClaw Manual Config

OpenClaw uses the native server block shape instead of the wrapped mcpServers object:

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

Behind a Reverse Proxy

If the open-source runtime is behind a reverse proxy with a public domain:

{
  "mcpServers": {
    "fluent": {
      "type": "http",
      "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 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, let the assistant guide the next step conversationally
• 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 a 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