Fluid Agentic MCP — Setup and Scope Guide

What do I need before I start?

Tenant URLs

Every Fluid organisation has its own tenant — a dedicated subdomain that hosts your data and API. Throughout this guide (and all Fluid API documentation), URLs are written as:

https://{tenant}.fluid.work

Replace {tenant} with your organisation's subdomain prefix. For example, if your Fluid instance is at https://robbie.fluid.work, then your tenant is robbie.

Always test integrations against your sandbox tenant before running against production. Contact your Fluid client success representative if you need a sandbox provisioned.

Quick start

The fastest way to get started is to import a single file that includes all Fluid MCP scopes:

https://docs.fluid.work/mcp/fluid.public.mcp.json

Option A — GitHub Copilot CLI / VS Code

1. Open your MCP server settings (user or workspace level).
2. Add a new MCP server entry and point it at https://docs.fluid.work/mcp/fluid.public.mcp.json.
3. When prompted, enter your fluidBaseUrl (your Fluid instance URL) and fluidPatToken (your PAT).
4. Copilot automatically launches the bridge command (npx @ivotoby/openapi-mcp-server) and discovers the available tools.
5. Try a test prompt: "List my projects in Fluid".

Option B — Claude Code / Claude Desktop

Claude clients use a different config shape (mcpServers) and have no prompt mechanism, so they cannot import fluid.public.mcp.json. Use fluid.claude.mcp.json instead, and set two environment variables first:

FLUID_BASE_URL   https://{tenant}.fluid.work
FLUID_PAT_TOKEN  your Base64 PAT token

Restart the client afterwards — a process only reads environment variables when it starts. Delete any servers you do not need from the file; fewer tools gives noticeably better agent behaviour.

For Claude Code you can register a single scope directly:

claude mcp add-json --scope user fluid-board-manager '{
  "command": "npx",
  "args": ["-y", "@ivotoby/openapi-mcp-server@1.16.1"],
  "env": {
    "API_BASE_URL": "https://{tenant}.fluid.work",
    "OPENAPI_SPEC_PATH": "https://docs.fluid.work/mcp/fluid-board-manager.openapi.json",
    "API_HEADERS": "Authorization:Basic <your-base64-PAT-token>,X-Fluid-Client:mcp-agent",
    "VERBOSE": "false"
  }
}'

Always include the X-Fluid-Client:mcp-agent header in manual setups — it identifies the traffic as agent-originated so your Fluid administrator can monitor and govern it (the all-in-one bundle adds it automatically).

A server showing as connected does not mean you are authenticated. Tool definitions come from the spec hosted here on docs.fluid.work, not from your tenant, so every tool lists successfully even with an expired or wrong-tenant token. Only a real tool call proves authentication.

Understanding the MCP scopes

Fluid splits its MCP interface into separate scopes so you can load only what you need. This keeps your agent focused, reduces tool clutter, and lets different teams (PM, portfolio, admin) work independently.

Why is it split up?

• Less noise: agents work better when they have fewer, more relevant tools. A PM agent does not need portfolio dashboard tools and vice versa.
• Team boundaries: a portfolio manager can load only the portfolio scope; a project manager can load only the PM scope. Each team sees only the tools they use.
• Security separation: token rotation is in its own scope so it cannot be accidentally triggered by a project-management prompt.
• Easier onboarding: new users can start with the all-in-one bundle, then switch to individual scopes as they get more comfortable.

What tools are in each scope?

Core platform (FluidApi)

The broadest scope — covers projects, boards, kanban, catalogs, and data feeds.

Account (FluidAccount)

A single-tool scope for credential maintenance.

Project Manager (FluidProjectManager)

Day-to-day PM operating tools for status cadence, RAID, and schedule governance.

To find a project first, use the Portfolio health project discovery tools (or the Core platform Project tools) — project listing is not part of this scope.

Board Manager (FluidBoardManager)

Focused kanban tools with guided card mutations and helpful validation of board column states.

Portfolio health (FluidPortfolioHealth)

Cross-project reporting and portfolio-level views for leadership and PMO.

Common use cases

Here are examples of what you can ask your agent once Fluid MCP is connected:

For project managers

• "Post this week's status update for Project Alpha — green overall, amber on schedule."
• "Show me all open risks and issues on Project Beta."
• "Push the UAT milestone out by two weeks."
• "Create a new risk: vendor delivery delay, red severity."
• "Give me a summary of my projects and their current RAG status."

For portfolio managers

• "Show me the top 10 projects by risk score."
• "Which projects have low governance scores?"
• "Give me an executive summary of the Digital Transformation portfolio."
• "List all projects and their latest RAG status."

For board / kanban users

These use the Board Manager scope (or the broader Core platform scope).

• "Show me all cards on the Content Marketing board."
• "Create a new task: Review Q3 campaign brief."
• "Move the 'Brand guidelines' card to Done."
• "What tasks are overdue on the Engineering board?"
• "Archive all completed tasks from last month."

Authentication and token management

Getting your first token

1. Log in to your Fluid instance.
2. Go to your user profile and generate a Personal Access Token (PAT).
3. Copy the Base64-encoded token value — this is your fluidPatToken.

Rotating your token

Tokens expire. To rotate before expiry without logging in to the Fluid UI:

1. Ask your agent: "Rotate my Fluid token" (it will call FluidAccount.createPersonalAccessTokenBase64).
2. Copy the new token value from the response.
3. Update your MCP configuration with the new fluidPatToken.

Frequently asked questions

MCP definition file reference