Connecting to Claude

This page is the technical setup guide for using Fluent with Claude Desktop and Claude Code.

You still talk to Claude directly. Fluent is the MCP server Claude uses for structured context and tools.

For the plain-language overview first, start here:

• Using Fluent with AI Apps

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

Claude Desktop

Early Access

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

Use this for early-access setups after your account has been provisioned. To use Fluent immediately, run the open-source runtime yourself.

Run Fluent Yourself

1. Generate the config automatically:

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

2. Or write the config directly to a file:

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

3. The generated config includes your bearer token (resolved from ~/.fluent/):

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

4. Restart Claude Desktop to pick up the new server.

Claude Bundle Structure

The mirrored Claude bundle lives at claude-plugin/fluent/ and includes these key assets:

File	Purpose
.claude-plugin/plugin.json	Claude plugin metadata
.mcp.json	Default managed-endpoint MCP config template
.mcp.hosted.json	Legacy managed-endpoint compatibility template
.mcp.oss.json	Open-source runtime template
.mcp.local.json	Legacy bridge asset

Claude Code

Early Access

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

Run Fluent Yourself

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

Early Access Reconnects

If Claude is using an older registration, reconnect and re-authorize. Fluent expects these scopes on the active grant:

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

Verifying the Connection

Once connected, ask Claude:

"What are my Fluent capabilities?"

Claude will call fluent_get_capabilities and show you:

• Contract version
• Available, enabled, and ready domains
• Onboarding state
• Profile summary
• Tool discovery hints

Start Here

Once the connection works, use Fluent through Claude itself:

"What can Fluent already help me with right now, and what should we set up first?"

That gives Claude room to inspect your Fluent state, decide what is ready, and handle the rest conversationally.

For a more direct first useful turn, try:

"Plan next week around my schedule and turn it into a grocery list I can actually shop from."

Troubleshooting

Tools not appearing

• Reconnect the MCP server in Claude settings
• Verify Fluent is running: curl http://127.0.0.1:8788/health
• Check your bearer token is correct

Stale tools after endpoint change

If you change the Fluent endpoint:

1. Reconnect the MCP server
2. Re-authorize if prompted
3. Remove stale credentials for the old endpoint if Claude keeps showing the previous tool set