MCP Integration: Technical Setup

Implementation reference for customer engineering, IT and security teams.

Connect a compatible AI assistant to Mosaic through a remote Model Context Protocol (MCP) server. The integration uses Mosaic-issued OAuth credentials and applies existing Mosaic permissions to every tool request. Organization access must be enabled before users connect.

1. Connection Configuration

2. System Architecture

The AI client requests Mosaic capabilities on behalf of the signed-in user. OAuth authorization establishes the connection; Mosaic checks the user, organization entitlement and applicable record permissions when tools execute.

A connection does not bypass existing Mosaic access controls.

Standard endpoint: https://app-api.mosaic.pe/mcp

Dedicated deployments use the Mosaic-provided tenant endpoint.

3. Authorization Sequence

Credentials are issued by Mosaic OAuth; Mosaic permissions still govern every operation.

Mosaic operates the OAuth 2.1 authorization server using authorization code flow with PKCE (S256). A compatible client discovers authorization metadata, registers its redirect URI, and opens the Mosaic sign-in and consent flow.

The user signs in through their normal Mosaic authentication path, including MFA or SSO where configured.

Mosaic issues tokens to the connected client; the client does not receive the user's Mosaic web session token.

4. Engineer Setup Checklist

• Confirm the AI client supports custom remote MCP servers and OAuth authorization.

• Verify the customer organization has MCP Connector enabled and users have active Mosaic accounts.

• Enter the correct MCP endpoint in the client's connector/server configuration.

• Complete the Mosaic sign-in and consent flow; do not manually copy tokens into prompts.

• Run a read-only validation such as listing accessible models or deals.

• If permitted, test a controlled write against a noncritical record and verify permissions.

5. Capabilities and Permissions

Important Boundaries

No delete tools are exposed. Watchlists are available for read-only retrieval.

Model creation and natural-language updates are supported for LBO and DCF models; other model types may be available for analysis.

Deal document tools return document names, not document contents.

6. Long-Running Builds and Exports

• Creating or updating an LBO/DCF model starts an asynchronous task. The client should check task status until completed, failed, canceled or additional context is required.

• For needs_context results, provide a fuller brief and resubmit the same task rather than starting a duplicate model.

• After completion, retrieve the Mosaic model URL and an Excel download link.

• Documents attached only to the AI conversation are not automatically available to Mosaic. Provide figures in the request or reference an eligible deal document already uploaded to Mosaic.

OAuth Token Lifecycle

Authorization codes are short-lived and single-use. Access tokens are scoped to the Mosaic MCP resource; refresh tokens rotate when used. Session expiry requires the user to authorize a new connection.

OAuth Discovery and Registration

The server publishes protected-resource and authorization-server metadata for compatible clients.

Clients use OAuth dynamic client registration and approved redirect URIs. Redirect URI validation and PKCE protect the authorization-code exchange.

The integration exposes a single OAuth scope; record-level rights remain governed by each user's Mosaic permissions.

7. Security and Data Governance

Access Revocation and Session Termination

Disconnecting the integration in an AI client may prevent refresh but does not necessarily invalidate an already-issued access token.

A previously issued access token may remain valid for up to 60 minutes. Mosaic can disable a user or turn off MCP for an organization; those changes are checked on the next tool call.

8. Troubleshooting

For dedicated deployment endpoints, access provisioning or integration assistance, contact your Mosaic customer team.