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 fastest setup path first, start here:

• Connect Fluent

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

Claude.ai Hosted Path

For Claude, start with the hosted connector path when your managed Fluent account is ready:

1. Open claude.ai.
2. Open Settings > Connectors.
3. Add this MCP URL:

https://mcp.meetfluent.app/mcp

4. Sign in with OAuth when Claude sends you to Fluent.
5. Ask Claude: "What can Fluent help me with?"

Use the scaffold generator below when you need Claude Desktop, Claude Code, generated config files, or a self-hosted open-source runtime.

Scaffold Generator

The scaffold generator produces advanced 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 client 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	Runtime path
--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 managed 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 package, use fluent-openclaw. The checked-in openclaw-plugin/fluent/ folder is the helper package fluent-openclaw-oss-helper.

Checked-In Client Bundles

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

Client	Bundle root	Key checked-in 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/	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 the copyable URL from Connect Fluent:

{
  "mcpServers": {
    "fluent": {
      "type": "http",
      "url": "<fluent-mcp-url>"
    }
  }
}

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

• openid
• profile
• email
• meals:read
• meals: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)

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

Meals and Style are available. Budgets can track user-provided grocery and clothing amounts.

Use fluent_get_context as the normal domain entrypoint.

Tool Discovery

The MCP tools/list endpoint is the authoritative public registry. Do not route to additional tools from historical capability hints.

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