Integration Guides

Connect Your AI Assistant to Mosaic

Connect Mosaic to Claude, ChatGPT, or another AI assistant so you can ask questions about your projects, people, time, and budgets in plain English.

What Is the Mosaic MCP Server?

The Mosaic MCP server connects your AI assistant directly to your Mosaic workspace using the Model Context Protocol (MCP) — an open standard for connecting AI assistants to the systems they need to answer questions.

Once connected, you can ask your assistant about your Mosaic data in plain English instead of building a report or exporting a spreadsheet.

Every question follows the same path:

  1. You ask a question in your AI assistant — "Which projects are over budget this quarter?"
  2. The assistant decides which Mosaic lookups or reports will answer it.
  3. The connector calls Mosaic on your behalf, signed in as you.
  4. Mosaic returns the matching records.
  5. The assistant reads the results and answers in plain language.

Because the assistant chooses which data to pull and how to summarize it, the way you phrase a question changes the quality of the answer. See What You Can Ask Mosaic for prompt patterns and a full list of the data and reports available.

Before You Start

  • A Mosaic account you can sign in to.
  • An AI assistant that supports custom MCP connectors — Claude, ChatGPT, and most other major assistants do.
  • Nothing to download, and nothing to install in Mosaic. There is no admin setup step, no API key to generate, and no integration to enable — you paste a URL and sign in through your browser.
🔒

Your existing permissions apply. You sign in as yourself, so your assistant can only reach the data you can already see in Mosaic. Connecting an assistant does not grant any extra access.

Your Connector URL

Connecting takes one Mosaic server URL. Because it depends on which Mosaic environment your organization is on, email [email protected] and we'll send you the right URL for your account.

Keep it handy — it's the only piece of setup information you need.

Set Up the Connector

  1. Open Settings → Connectors and choose Add custom connector.
  2. Give it a name — for example, Mosaic.
  3. Paste the connector URL into the server URL field.
  4. Save the connector, then choose Connect. A browser window opens on Mosaic's sign-in page.
  5. Sign in with your usual Mosaic credentials — email and password, your multi-factor code if you use MFA, or your company's single sign-on.
  6. Approve access when Mosaic asks.
  7. Enable the connector in your conversation and ask a Mosaic question to confirm it's working.

How Signing In Works

You always sign in through Mosaic's own login page in your browser. Your password is never shared with the AI app, and the app never sees your Mosaic credentials — it only receives a scoped access token. Multi-factor authentication and single sign-on both work normally.

Your AI app holds that token, so you don't sign in for every question. When it expires, you'll be prompted to authorize again through the browser.

Signing Out and Removing the Connector

Open your AI app's connector settings, then either disable the Mosaic connector to stop it being used, or delete it to remove the connection and revoke its access entirely.

Updating

Nothing to maintain — the connector is hosted by Mosaic, so improvements and new capabilities appear automatically.

Security and Privacy

  • All traffic is encrypted in transit over HTTPS.
  • You authenticate against Mosaic directly. Sign-in happens on Mosaic's login page, and the AI app receives only a time-limited access token — never your password.
  • Access is scoped. Each token is bound to one Mosaic user and the Mosaic MCP endpoint it was issued for. It can't be reused elsewhere.
  • Your Mosaic permissions are enforced at the data layer, on every request, exactly as they are in the Mosaic app.
  • Sessions expire and are re-authorized through the browser.
  • Requests are logged. Mosaic records the full lifecycle of every MCP request, so activity can be traced and audited.
⚠️

Data leaves Mosaic when you use an AI assistant

Anything your assistant retrieves is processed by your AI provider, and Mosaic doesn't control how that provider stores or retains it. Before connecting, especially if you work with rate, cost, or client financial data:

  • Review your AI provider's data-retention and training policies.
  • Prefer a business or enterprise plan, where data is typically excluded from model training.
  • Turn off model training on your conversations if your provider offers the option.
  • Ask narrow questions rather than pulling large exports you don't need.

Troubleshooting

My assistant says it can't see my Mosaic tools

Confirm the connector is enabled for the conversation you're in — most apps require you to switch it on per chat. Check its status in your connector settings too: if it shows as not connected, authorize it again. If it still doesn't appear, restart the AI app.

Sign-in didn't work, or the browser window expired

The sign-in window times out after a couple of minutes, so if you stepped away, simply start again — reconnect from your app's connector settings to get a fresh window.

I got an authorization or access denied error

This usually means the connector URL doesn't match your Mosaic environment. Confirm your URL with [email protected], then remove and re-add the connector to authorize again.

Answers are slow, incomplete, or cut off

Broad questions over long date ranges pull a lot of records. Narrow the range, filter to specific projects or people, and ask for one slice at a time. See Getting Better Answers for guidance.

Next Steps

Head to What You Can Ask Mosaic for example prompts, the full list of data and reports your assistant can pull, and tips for getting accurate answers.

If something isn't working, reach out to [email protected].

Updated about 23 hours ago