Datarails AI Connector: Technical documentation

Architecture

Deployment model

The connector is a remote MCP server that Datarails hosts. You have nothing to install, host, or patch, and nothing runs inside your network.

  • Transport. Streamable HTTP over TLS to one public endpoint: https://mcp.datarails.com/mcp.
  • Direction of traffic. Outbound only. Your AI client calls Datarails, and Datarails never opens a connection into your network. You don't need an inbound firewall rule, a VPN tunnel, or a reverse proxy.
  • What the MCP service does. It checks the caller's token, turns the tool call into a request to the Datarails API in your environment, and returns the result.
  • Storage. Customer data only passes through the service. No financial records are kept after a request finishes. The service holds only short-lived session and sign-in state.
  • Authorization. The Datarails API checks every request against the calling user's own Datarails permissions. The MCP service has no data store of its own and can't grant anyone more access than they already have.

What you need

On the Datarails side
  • An active AI Connector subscription for your organization. 
  • A Datarails user account for each person who will connect, with the roles and permission groups you want that person to have.
On your side
  • An AI client that supports MCP, such as Claude, ChatGPT, or Microsoft Copilot.
  • Outbound HTTPS (TCP 443) from the AI client to the hosts listed below.
  • Git: If planning on using the FinanceOS plugin.

Hosting and data residency

  • The MCP service runs in the United States. It is stateless and stores no customer data.
  • Your financial data stays at rest only in your existing Datarails environment and its region. The connector doesn't move, copy, or replicate it to another region.
  • Datarails is evaluating region-aware routing behind the same URL, so that requests are also processed in your environment's region. There's no committed delivery date. If your policy requires in-region processing, raise it with your Customer Success Manager before you roll out.

Hosts to allow

Host Purpose
mcp.datarails.com The MCP endpoint your AI client calls for every tool call. It also handles the OAuth authorization, token, and revocation requests.
auth.datarails.com, or your region's sign-in host The Datarails sign-in page, where users log in, choose an environment, and approve access.
Your Datarails environment host (for example app.datarails.com) Serves the Datarails data API.

Authentication and access scope

Every user signs in as themselves

There's no shared service account, no organization-wide API key, and no credential for an administrator to hand out. Each person signs in with their own Datarails account. If two users connect the same AI platform to the same organization, they get two separate sessions, and each one can be traced to that user.

How sign-in works

  1. The first time the user connects, the AI client opens the Datarails sign-in page in their browser.

  2. The user signs in to Datarails, through your SSO if it's set up, chooses the environment, and approves access on a consent screen.

  3. Datarails sends an authorization code back to the client. The client exchanges the code for tokens at mcp.datarails.com, using the OAuth 2.0 Authorization Code Flow with PKCE (RFC 7636, S256) and a state parameter that protects against cross-site request forgery.

  4. The client receives a short-lived access token and a refresh token. Each time the refresh token is used, it's replaced with a new one and the old one stops working.

  5. The AI client stores the tokens in its own credential store:

    - Hosted platforms such as Claude.ai and ChatGPT keep them in the platform's connector credential store.

    - Locally installed clients store them in their own way. For example, Claude Code uses the macOS Keychain on a Mac and a credentials file in the user's profile folder on Windows and Linux.

Your Datarails password is never stored by the AI client or written into a configuration file.

What the token allows

  • The user's own Datarails permissions, and nothing more. The token is tied to the user and organization that issued it. Datarails checks every tool call against that user's role (Super Admin, Admin, Contributor, or Viewer) and permission groups, exactly as it does in the Datarails web application.
  • No access to other organizations. The organization comes from the token, never from anything the AI assistant sends, so one user's session can't reach another organization's data.
  • No narrower AI-only scope. The connector can't be limited to less than the user's Datarails role. If a user can see a data model in Datarails, they can query it through the connector. To keep a data set away from AI, restrict it in that person's Datarails permissions.

What the AI Connector can't do

  • With the current tools, the connector can't:

  • Write, change, or delete financial data, fileboxes, templates, formulas, or reports.
  • Create, change, or delete users, roles, or permissions.
  • Change organization settings or turn itself on. Only an administrator can turn the connector on, in the Datarails web application.
  • Reach data the signed-in user isn't already allowed to see.
  • Reach another organization's data.

Important: The tool list depends on the connector version, and Datarails may add tools over time, including tools that can write data. This article is updated when the list changes, but the list your AI client shows is always the current one for your organization. Review it before and after a connector upgrade.

Turning access off

To... Do this Takes effect
Turn a platform off for everyone A Super Admin turns the platform off in AI Center. Immediately. The platform is blocked when it tries to connect and is hidden from navigation.
Turn one person off Deactivate the user in Datarails, or remove the permissions in question. On their next request, and no later than when their short-lived access token expires.
End a session from the AI client The user disconnects the connector. The refresh token is revoked on the server, not just deleted from the user's device.

Tool inventory

Every tool the connector offers today is read-only. None of them creates, changes, or deletes anything in Datarails. They can't write to fileboxes, upload or edit data, or change formulas, models, permissions, or users.

What "read-only" means here. It describes the tools available today. It isn't an enforced permission setting: there's no read-only mode that limits the connector to less than the user's Datarails permissions, and tools that can write data are on the AI Connector roadmap. If a person must not change a data set, control that with their Datarails permissions rather than relying on the tool list.

The tool list your AI client shows for the connector is always the current one for your organization. Use it to check what's described below.

Discovery and metadata

Tool What it does
get_connector_status Reports whether the connector is enabled for the organization
get_workflow_guide Returns the organization's settings that determine how numbers read: name, fiscal year, default and available reporting currencies, and the default budget and forecast scenarios
list_data_models Lists the tables and data models the user is allowed to see
get_fields_by_id Returns a table's columns, types, and descriptions
list_aliased_fields Returns a table's business-friendly field names (aliases) and descriptions
list_business_metrics Lists the organization's defined KPIs and metric definitions
list_xl_functions Lists the named XL functions used in Excel DR.GET formulas
list_filebox Lists Filebox folders, files, templates, and lookup tables (names and structure only)
list_company_profile_sections Lists the sections of the organization's company profile
get_company_profile_sections Returns the content of the named company profile sections
get_org_users Returns the organization's users with their role and department

For privacy reviewers: get_org_users returns the names and email addresses of your Datarails users. The data tools return whatever your tables contain. If those tables hold personal data, such as HRIS, customer, or vendor records, that data can be returned too, within the user's permissions.

Data retrieval

Tool What it does
get_data_by_id Returns rows from a table, addressed by ID, with optional column selection and filters
get_data_by_alias Returns rows from a table, addressed by its business-friendly name, with optional column selection and filters

Aggregation and distinct values

Aggregations run in two steps. A start_ tool sends the query and returns a reference to it, and the matching get_ tool fetches the result. The start_ tools only read data; they don't create or save anything.

Tool What it does
start_aggregation_by_id Starts a grouped calculation (SUM, COUNT, AVG, MIN, MAX, and similar) on a table addressed by ID
get_aggregation_result_by_id Fetches the result of that calculation
start_aggregation_by_alias Starts a grouped calculation on a table addressed by its business-friendly name
get_aggregation_result_by_alias Fetches the result of that calculation
start_distinct_values_by_id Starts a lookup of a field's distinct values, addressed by ID
get_distinct_values_result_by_id Fetches the distinct values found
start_distinct_values_by_alias Starts a lookup of a field's distinct values, addressed by business-friendly name
get_distinct_values_result_by_alias Fetches the distinct values found

Profiling and reference data

Tool What it does
profile_numeric_fields Returns SUM, AVG, MIN, MAX, and COUNT for numeric fields
profile_categorical_fields Returns distinct counts and sample values for categorical fields
get_currency_rates Returns the organization's most recent FX rates (USD base)

Logging, audit, and data handling

What data leaves Datarails

  • Only the answer to each tool call. When a user asks a question, the AI assistant makes one or more specific, filtered tool calls. Datarails returns only the rows, totals, or metadata those calls ask for, already limited by the user's permissions.
  • No bulk copying. There's no copy of your data set, no sync job, no export of your data model, and no background transfer. Datarails doesn't push data to any AI vendor. Data moves only when a user makes a request.
  • Totals first. Most questions are answered with calculations run on the Datarails server, which return grouped totals rather than individual records. Row-level results come in pages of 100 rows by default (500 at most), and calculation results are capped at a maximum response size, so no single call can pull an unlimited extract.
  • Encrypted in transit. All traffic between the AI client, the MCP service, and the Datarails API uses TLS 1.2 or higher.
  • Not stored by the MCP service. Financial values pass through in memory while a request runs and aren't saved.

Retention and export

  • Datarails keeps audit records in line with its SOC 2 obligations. The exact retention period for records is still being set. Contact support@datarails.com for the period that applies to your contract.
  • If your security team needs audit events sent to your own SIEM, reach out to Support. Exports are set up for each customer.

Data returned to the AI client becomes part of that conversation on the AI platform. From then on it's covered by your organization's agreement with the AI vendor — its retention, training, and regional processing terms — not by Datarails'. Datarails controls who can ask, what they're allowed to receive, and the record that they asked. It doesn't control what the AI platform does with the answer. We recommend reviewing the AI vendor's enterprise data terms alongside this document.

Summary

  • Per-user sign-in: OAuth 2.0 Authorization Code Flow with PKCE, with explicit consent and no shared credentials.
  • Short-lived tokens: access tokens expire quickly, refresh tokens are replaced each time they're used, and tokens can be revoked on the server.
  • Credential storage: tokens are held by the AI client in its own credential store. Your Datarails password is never stored by the AI client.
  • Encryption: TLS 1.2 or higher for all data in transit.
  • Organization isolation: the organization comes from the token and is enforced on every query.
  • No storage in the MCP service: customer financial data only passes through.
  • Rate limiting on the service.
  • Admin control of which AI platforms each organization allows.
  • Session-level audit log visible to Super Admins.

Datarails is SOC 2 certified. To confirm how the AI connector is covered in the current report, request the report, or have a security questionnaire completed, contact support@datarails.com.



© Datarails Ltd. All rights reserved.

Updated

Was this article helpful?

0 out of 0 found this helpful

Have more questions? Submit a request