FinanceOS AI Integration (MCP)

FinanceOS allows you to securely connect your AI assistant to your Datarails financial data.

Using the Model Context Protocol (MCP), you can analyze data, profile tables, run queries, generate reports, and extract validated financials directly from the AI platform you already use.

FinanceOS works with:

• Claude Code

• Claude CoWork

• Claude.ai

• ChatGPT

• Lovable

• CoPilot - Coming soon

What You Can Do

Once connected, your AI assistant can:

• Discover available financial tables and data models
• Understand schema, field aliases, and business descriptions
• Profile data quality
• Run filtered, row-level queries
• Perform server-side aggregations
• Retrieve your organization's defined business metrics and KPIs
• Produce charts, Excel models, and reports in your AI client
• All access is authenticated per user via OAuth and encrypted in transit.

All access is securely authenticated via OAuth.

Connecting Your AI Assistant

FinanceOS provides a secure MCP endpoint:

https://mcp.datarails.com/mcp

Authentication is handled automatically using the OAuth 2.0 Authorization Code Flow with PKCE. 
On first connection, your AI client redirects you to log in to Datarails and approve access.

Setup Instructions by Platform

Claude Code

Run:

claude mcp add datarails-finance-os --transport http https://mcp.datarails.com/mcp

Restart Claude Code. 
The server appears in your MCP tools list, and you are prompted to authenticate on first use.

Claude Desktop

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "datarails-finance-os": {
      "type": "streamable-http",
      "url": "https://mcp.datarails.com/mcp"
    }
  }
}

Restart Claude Desktop and authenticate when prompted.

Other MCP Clients

Configure your MCP client with:

https://mcp.datarails.com/mcp

The client will redirect you to log in on first connection.

Integration Architecture

Deployment model

The connector is a Datarails-hosted remote MCP server. There is nothing to install, host, or patch on your side, and nothing is deployed inside your network.

• Transport — Streamable HTTP over TLS to a single public endpoint, https://mcp.datarails.com/mcp.
• Direction of traffic — Outbound only. Your AI client calls Datarails; Datarails never initiates a connection into your network. No inbound firewall rule, VPN tunnel, or reverse proxy is required.
• Role of the MCP service — It validates the caller's token, translates the AI assistant's tool call into a call against the FinanceOS API in your Datarails environment, and returns the result.
• Storage — The service is pass-through for customer data. No financial records are persisted in the MCP layer beyond the lifetime of the request; it holds only short-lived session and authentication state.
• Authorization boundary — Every request is authorized by the FinanceOS API against the calling user's own Datarails permissions. The MCP layer holds no data store of its own and cannot widen access.

What is required on the Datarails side

• An active FinanceOS AI connector subscription for your organization (this is a paid feature).
• The connector enabled for your organization by a Super Admin in AI Center > Manage AI Connectors. Enablement is per organization, not per user. A connector that is toggled off is blocked at runtime.
• A Datarails user account for each person who will connect, with the roles and permission groups you want that person to have.

What is required on your side

• An MCP-capable AI client (for example Claude, Claude Code, or ChatGPT).
• Outbound HTTPS (TCP 443) from the AI client to the Datarails hosts listed below.
• Browser access for each user to complete the one-time OAuth login and consent screen.
• No agent, no on-premises component, no service account, no API key, and no changes to your Datarails data model.

Hosts to allow

Hosting and data residency

• The MCP service is currently hosted and processed in the United States. It is stateless and stores no customer data.
• Your financial data continues to live at rest only in your existing Datarails environment and its region. The connector does not move, copy, or replicate it to another region.
• Region-aware routing behind the same single global URL, so that request processing also stays in your environment's region, is under evaluation and has no committed delivery date. If your policy requires in-region processing, raise it with your Customer Success Manager before rollout.

Authentication and Access Scope

Per-user authentication — no shared service account

Every person authenticates as themselves. There is no shared service account, no tenant-wide API key, and no credential that an administrator distributes to users. Two different users connecting the same AI platform to the same organization receive two separate, individually attributable sessions.

How the flow works

1. On first use, the AI client opens auth.datarails.com in the user's browser.
2. The user signs in to Datarails, including through your SSO if it is configured, selects the environment, and explicitly approves access on a consent screen.
3. Datarails returns an authorization code to the client, exchanged using OAuth 2.0 Authorization Code Flow with PKCE (RFC 7636) plus a state parameter for CSRF protection.
4. That token is exchanged with your environment's token server for a short-lived JWT access token and a refresh token. Refreshes rotate the refresh token and invalidate the previous one.
5. Tokens are held by your AI platform in its own connector credential store; where a locally installed client is used, they are stored in the operating system keyring (macOS Keychain, Windows Credential Manager, Linux Secret Service). No Datarails password, cookie, or secret is written into a config file or a plugin setting.

What the token grants

• The user's own Datarails permissions, and nothing more. The token is bound to the issuing user and organization. Every tool call is evaluated by FinanceOS against that user's role (Super Admin, Admin, Contributor, Viewer) and permission groups, exactly as if they had opened the Datarails web application.
• Cross-organization access is architecturally prevented. Tenancy is derived from the token, never from anything the AI assistant sends in the request, so one user's session cannot reach another organization's data.
• Access is not narrowed below the user's Datarails role. There is currently no separate, narrower MCP-only scope: a user who can see a data model in Datarails can query it through the connector. If a person should not reach a data set through AI, restrict it with their Datarails permissions.

Administrative control and revocation

• Turn the platform off for everyone — a Super Admin disables the connector in AI Center. Disabled platforms are blocked at runtime and hidden from navigation.
• Turn a person off — deactivate the user, or remove the permissions in question, in Datarails. The change applies on their next request, and at the latest when their short-lived access token expires.
• End a session from the client — the user disconnects, which revokes the refresh token server-side rather than only deleting it locally.

Tool Inventory: Read vs. Write

Every tool in the connector's current inventory is read-only. No tool in the list below creates, updates, or deletes anything in Datarails: no writing to fileboxes, no uploading or editing data, no changing formulas, models, permissions, or users.

Read the scope of that statement carefully. Read-only is a property of the tools currently published, not an enforced permission scope — there is no separate read-only mode that constrains the connector below the calling user's Datarails permissions. Write-capable tools are on the FinanceOS roadmap. Where it matters that a person cannot change a data set, control that with their Datarails permissions rather than relying on the tool inventory.

The inventory in force for your organization is always the tool list your AI client displays for the connector. Use it to verify what is described below.

Discovery and metadata

Data retrieval

Aggregation and distinct values

Aggregations run asynchronously: a start_ tool submits a query and returns a handle, and the matching get_ tool retrieves the result. The start_ tools initiate a server-side read query. They create and persist nothing.

Profiling and reference data

What the connector cannot do

• It cannot write, modify, or delete financial data, fileboxes, templates, formulas, or reports.
• It cannot create, modify, or delete users, roles, or permissions.
• It cannot change organization settings or enable itself — connector enablement is an administrator action in the Datarails web application only.
• It cannot reach data the authenticated user is not already permitted to see.
• It cannot reach another organization's data.

Important: the exact tool list depends on the connector version, and Datarails may add tools over time, including write-capable tools. This article is updated as the inventory changes, but the authoritative list for your organization at any moment is the one your AI client displays. Review it before and after a connector upgrade.

Logging, Audit, and Data Handling

What Datarails records today

AI connector governance and adoption are recorded in AI Center and reviewed by Super Admins in the Datarails web application, under AI Center > Admin Control:

• Administrative actions — enabling or disabling an AI connector for the organization, and prompt library changes.
• Adoption and session activity — monthly active users, total sessions, connected platforms, usage over time, and per-member engagement.
• Audit Log — a session-level list showing session ID, the member, the AI platform, activity time, duration, and status, with grouping, filtering, sorting, and free-text search, plus a side panel showing a single session's chronological event timeline.

Audit visibility is strictly per organization. There is no cross-tenant log visibility, and end users cannot see the audit log — it is available to Super Admins only.

What is still being built

Be precise with your security team on this point. Tool-call-level audit events emitted by the MCP server itself — a durable, per-query record of each individual tool call, its filters, and the volume returned — are in development and are not yet complete. The AI Center surfaces described above are live, but full per-query attribution from the MCP layer should not be assumed as an available control when you plan your rollout. Ask your Customer Success Manager for the current status before you depend on it.

Retention and export

• Datarails' commitment is to retain audit records in line with its SOC 2 obligations. The specific retention period for AI Center records is being finalized — ask your Customer Success Manager or Datarails Support for the period applicable to your contract.
• In-product review, filtering, and search in the Audit Log page is available today.
• If your security team needs audit events delivered into your own SIEM, ask your Customer Success Manager. Export arrangements are set up per customer.

What data actually leaves Datarails

• Only the response to each individual tool call. When a user asks a question, the AI assistant issues one or more specific, filtered tool calls, and Datarails returns only the rows, aggregates, or metadata those calls requested — already constrained by that user's permissions.
• No bulk replication. There is no dataset copy, no sync job, no export of your data model, and no background transfer. Datarails does not push data to any AI vendor; data moves only in response to a user-initiated request.
• Queries are aggregate-first by design. Most analysis is answered by server-side aggregation, which returns grouped totals rather than row-level records. Row-level retrieval is paginated (100 rows per page by default) and aggregation responses are capped by a response-size limit, so a single call cannot pull an unbounded extract.
• Encryption — all traffic between the AI client, the MCP service, and the FinanceOS API is encrypted in transit with TLS 1.2 or higher.
• No persistence in the MCP layer — financial values pass through in memory for the duration of the request and are not stored there.

The point your security team should weigh

Whatever data is returned to the AI client becomes part of that conversation on the AI platform, and is then handled under your organization's own agreement with that AI vendor — its retention, training, and regional processing terms, not Datarails'. Datarails controls who can ask, what they are allowed to receive, and the record that they asked. It does not control what the AI platform does with the answer once delivered. Reviewing the AI vendor's enterprise data terms alongside this document is the recommended next step.

Security Summary

• OAuth 2.0 Authorization Code Flow with PKCE — per-user authentication, explicit consent, no shared credentials.
• Short-lived JWTs with rotating refresh tokens and server-side revocation.
• Credential storage in the AI platform's connector credential store, or the OS keyring for locally installed clients — never in configuration files.
• TLS 1.2 or higher for all data in transit.
• Multi-tenant isolation — tenancy derived from the token, enforced on every query.
• No customer financial data stored in the MCP layer — pass-through only.
• Rate limiting on the service.
• Per-organization admin governance of which AI platforms are permitted.
• Session-level audit trail visible to Super Admins.

Datarails is SOC 2 certified. To confirm how the AI connector is covered in the current report, or to request the report or a completed security questionnaire, contact your Customer Success Manager.

Troubleshooting

Tools are missing, or a call fails with connector_not_enabled

Problem: The connector authenticates but exposes no tools, or tool calls are rejected.

Solution:

• Run get_connector_status, which is always available, to confirm whether the connector is enabled for your organization.
• Ask a Super Admin to check AI Center > Manage AI Connectors and enable the platform you are using.
• Confirm your organization has an active FinanceOS AI connector subscription.

A user sees fewer tables than a colleague

Problem: Two users connected to the same organization see different data.

Solution: This is expected. The connector inherits each user's Datarails permissions. Compare the two users' roles and permission groups in Datarails; the connector will reflect any change you make there.

Authentication fails or the session expires

Problem: The browser login does not complete, or the client reports an expired session.

Solution:

• Confirm the client can reach auth.datarails.com, mcp.datarails.com, and your Datarails environment host over HTTPS.
• Complete the browser consent step within the timeout; if it lapses, start the authentication again.
• If the refresh token has expired or been revoked, disconnect and re-authenticate.

Frequently Asked Questions

Does Claude authenticate per user, or through a shared service account?
Per user. Each person authenticates to Datarails in their own browser and receives a token bound to their own identity and organization. There is no shared service account and no distributed API key.

Does the connector inherit that person's Datarails permissions?
Yes. Every request is authorized against the calling user's role and permission groups, exactly as in the Datarails web application. It cannot see more than they can.

Can the AI assistant change anything in Datarails?
Not with the current tool inventory. Every tool published today is read-only — there is no write, update, or delete action, and no ability to modify users, permissions, or settings. Note that this is a property of the tools currently published rather than an enforced read-only scope, and write-capable tools are on the roadmap, so use Datarails permissions to control what a person may change.

Do we need to install anything, or open an inbound firewall rule?
No. The connector is a Datarails-hosted service reached over outbound HTTPS. Nothing runs in your environment and nothing connects inbound to your network.

What data actually leaves Datarails?
Only the result of each specific, user-initiated tool call, already filtered by that user's permissions. There is no bulk export, replication, or background sync.

Where is the service hosted?
The MCP service is currently hosted in the United States and is stateless, storing no customer data. Your financial data remains at rest in your existing Datarails environment and region.

Can we see who queried what, and when?
In part, today. Super Admins review a session-level audit log in AI Center — member, AI platform, timing, status, and a per-session event timeline — along with administrative actions such as enabling or disabling a connector. Tool-call-level audit events emitted by the MCP server itself are still in development, so ask your Customer Success Manager for the current state before relying on per-query attribution.

Are there query limits?
Yes. Row-level retrieval is paginated, returning 100 rows per page by default with offset-based paging. Aggregation results return one row per requested group, subject to a response-size limit; when a result is capped, the response says so and reports the total row count so the query can be narrowed. Rate limiting also applies at the service level.

Which AI platforms can we allow?
A Super Admin decides per organization in AI Center. Claude and ChatGPT are enabled by default; Lovable and Copilot can be enabled by an administrator; Gemini is coming soon and cannot yet be enabled. Platforms you have not enabled are blocked at runtime and hidden from navigation.

Do we need a security questionnaire or SOC 2 report?
Datarails is SOC 2 certified. Contact your Customer Success Manager to request the current report, confirm how the AI connector is covered in it, or have a security questionnaire completed.

Need Help?

If you need assistance connecting your AI platform to FinanceOS, or your IT and security team needs additional detail for a review, contact Datarails Support or your Customer Success Manager.

Updated August 26, 2026 07:33