---
name: fluent-mcp-core
description: Official Fluent Commerce CLI MCP server setup and operations. Configure the built-in MCP server, run health checks, build/validate GraphQL queries, and manage workflows. Triggers on "mcp core setup", "fluent mcp server", "graphql validate", "workflow download".
user-invocable: true
allowed-tools: Bash, Read, Write, Edit, Glob, Grep
argument-hint: <operation> [--profile name] [--retailer ref]
cursor-tier: auto
---

# Fluent MCP Core

Setup and operations guide for the official Fluent Commerce CLI MCP server.

## When to Use

- Setting up the built-in MCP server for a project
- Building and validating GraphQL queries against the schema
- Listing or downloading workflow definitions
- Diagnosing MCP server connectivity issues

## Setup

### 1. Ensure CLI Profile Exists

```bash
fluent profile active
fluent profile list
```

### 2. Configure `.mcp.json`

Add to your project root:

```json
{
  "mcpServers": {
    "fluent-mcp": {
      "command": "fluent",
      "args": ["mcp", "server", "--stdio"],
      "env": {
        "FLUENT_PROFILE": "YOUR_PROFILE"
      }
    }
  }
}
```

### 3. Verify Connection

Use `health.ping` tool to confirm the server is connected and the profile is valid.

## Operations

### Health Check

Run `health.ping` to confirm config readiness and SDK adapter status.

### GraphQL

| Operation | Tool | Description |
|-----------|------|-------------|
| Discover fields | `graphql.listRoots` | List all query/mutation root fields |
| Explore type | `graphql.generateFull` | Generate maximal query for a root field |
| Build query | `graphql.buildQuery` | Create query from field selections |
| Validate | `graphql.validate` | Check query against schema |
| Execute | `graphql.execute` | Run query/mutation |

**Response contract for `buildQuery` / `validate`:** These tools return `{ ok: true, valid: true|false }`. Check the `valid` field (not `ok`) to determine if the query passed schema validation. `ok: true` means the tool ran successfully; `valid: false` means the document has schema errors (see `errors` / `validationErrors` array for details).

### Workflows

| Operation | Tool | Description |
|-----------|------|-------------|
| List | `workflow.list` | All workflows for a retailer |
| Download | `workflow.download` | Full workflow JSON with rulesets |

## Troubleshooting

| Symptom | Cause | Fix |
|---------|-------|-----|
| `health.ping` fails | No active profile | Run `fluent profile active` |
| Auth error | Expired token | Run `fluent profile update <PROFILE> --password <new-pass>` |
| Empty workflow list | Wrong retailer ref | Check `fluent profile retailers <PROFILE>` |
| Server won't start | CLI not in PATH | Install from [docs.fluentcommerce.com](https://docs.fluentcommerce.com/building-blocks/fluent-cli-package) |

## Transport Modes

Both MCP servers support stdio (default). The **extension server** also supports HTTP Streamable transport for remote clients, CI/CD pipelines, and multi-session usage. See `/fluent-mcp-tools` for HTTP transport configuration.

## MCP Core vs MCP Extension

Use **MCP Core** when you need:
- Query building and schema validation
- Workflow listing and downloading
- Simple GraphQL with CLI profile auth

Use **MCP Extension** (`mcp` group) when you need:
- Event dispatch (build, send, verify)
- Auto-paginated queries
- Batch mutations and data ingestion
- Webhook validation
- HTTP transport mode (remote clients, CI/CD)
- Tool annotations (readOnlyHint, destructiveHint)
