The MCP endpoint

The MCP endpoint is xMatix's built-in server for the Model Context Protocol: it lets an MCP-capable assistant (Claude, ChatGPT, Claude Code and similar hosts) work with your organization's data and setup as a signed-in user, inside that user's permissions. The protocol also works in the other direction: administrators can register external MCP servers so the platform's own Sense agents can call your tools. This page is the developer and operator reference for both directions. For the shorter end-user guide, see Using Sense from Claude, ChatGPT or Claude Code.

Overview

When to use it

• Use the MCP endpoint when you want an AI assistant or agent framework to answer questions over your records, run your saved reports, or help an administrator configure the organization. Apart from the endpoint URL, nothing about your organization needs to be configured in the client.
• Use the data API instead when you are writing a program. Your code then decides exactly what it reads and submits, and no model sits in between.
• Register an external MCP server when a Sense agent inside xMatix needs a tool that lives in another system, for example a pricing service or an internal lookup.

How xMatix handles it

The assistant is the model. The endpoint never runs Sense or the Setup Copilot on the assistant's behalf. It returns data and performs governed actions, and the assistant does its own reasoning. Connected assistants therefore use no AI credits.

Transport. The endpoint accepts JSON-RPC 2.0 over POST and runs in stateless mode. You can send one message or a batch of up to 20. The supported methods are initialize, ping, tools/list, tools/call, prompts/list and prompts/get; resources/list answers with an empty list. GET answers 405 because the server opens no stream of its own, and DELETE is accepted as a no-op. The negotiated MCP-Protocol-Version is echoed on every response.

Sign-in. A call without a token answers 401 with protected-resource metadata. That tells a standards-compliant assistant which authorization server to use. The authorization server supports OAuth 2.1 authorization code with PKCE (S256 is mandatory). A client identifies itself with a Client ID Metadata Document, with dynamic registration, or as a client an administrator registered in advance. The user signs in with the organization's normal xMatix sign-in and picks the organization or organizations to grant on a consent page. The assistant then receives an access token that lives 60 minutes and a refresh token that rotates on every use. If a refresh token is used a second time, the whole token family is revoked. The consent page offers Not you? so a user can sign in with a different account without signing out of the browser.

Scopes set the ceiling:

When the organization has not allowed writes, xmatix.write and xmatix.setup are dropped as the token is issued, whatever the assistant asked for. The scope returned with the token is authoritative.

What governs every call. Each request passes the same checks in order. The user must be a member of the organization (otherwise 403 tenant_forbidden). The organization must not be locked (otherwise 423 tenant_locked). The organization must have external assistants on and must accept this assistant (otherwise 403 external_assistants_disabled). After that, a tool is offered only when four filters all agree:

1. the token carries the tool's scope;
2. the tool does not change data, or the organization is neither read-only nor write-blocked. While it is, every write tool and every setup tool that is not read-only is hidden;
3. for the data, report, dashboard, dataset and knowledge tools, the organization's Sense capability grants (the union of its active agents' grants, minus capabilities whose licence the user lacks) include the matching Sense tool;
4. the tool is available. For example, the setup tools appear only where the setup tool service is available.

The tool then runs as the user. Their security profiles, record security, restriction rules and company scope apply on the server exactly as in the product. Every tools/call is audited under the user's name, and setup calls also land in the setup audit trail as if the administrator had used the Setup screens.

The tool set

The setup tools are the Setup Copilot's own tool layer served without its model. They use the same definitions, the same setup APIs and the same permission checks. Each one is annotated read-only or destructive, so a well-behaved assistant runs reads freely and asks you before a change. The tool for storing integration secrets is never offered to an external assistant: enter credentials in the xMatix application and reference them from integration configuration.

The platform guides are also offered as MCP prompts (prompts/list, prompts/get), so an assistant can load a module guide into its context.

Working across organizations

A user who belongs to several organizations can tick more than one on the consent page. Organizations whose administrator has not turned on external assistants are not offered there. The token then carries a default organization, and the assistant has three ways to act in another granted one:

On a connection that covers several organizations, every tool result starts with [organization: …], naming where the call ran. switch_organization without an argument returns the choices. On a single-organization connection it answers that the person must reconnect and tick more organizations. The organization tools are offered to every connection whatever it covers, because assistants cache the tool list. When a switch changes which tools are on offer, the server sends notifications/tools/list_changed with the response.

Prerequisites

• An administrator with Manage AI agents has turned on Allow external assistants for the organization. It is off by default.
• The user has an xMatix account in that organization. The assistant can never do more than the user could do in the product.
• For writes: Allow writes is on, and the user has the same permission in the product. For setup tools: the user is an administrator with the matching setup rights.

Procedure

Step 1 — Turn on external assistants

1. Open Setup → Sense AI Studio → Configuration → External assistants. The page header shows Assistants (Enabled or Off), Writes (Allowed or Read-only), Active connections and the MCP endpoint URL.
2. Select Settings. The External assistant settings dialog opens.
3. Switch on Allow external assistants.
4. Optionally switch on Allow writes (create/update records; setup changes for administrators).
5. Optionally pick Approved assistants (optional). Leave it empty to allow any registered assistant.
6. Select Save. Copy the MCP endpoint URL from the header to give to your users.

Step 2 — Connect an assistant

Each user connects their own assistant with the MCP endpoint URL:

1. Claude (web or desktop): Customize → Connectors. Select Connect on xMatix if it is listed; otherwise choose Add custom connector and paste the URL.
2. ChatGPT: Settings → Connectors → Create (developer mode) with the same URL. search and fetch make the connector usable in deep research.
3. Claude Code: claude mcp add --transport http xmatix <MCP endpoint URL>. On organizations where the External assistants dialog offers it, you can instead install the plugin with /plugin marketplace add xMatixAI/claude-plugin, then /plugin install with the plugin name the dialog shows, then /mcp to sign in.
4. Editor hosts such as Cursor and VS Code: add the URL as a remote server. These hosts register with their own app redirect, which the authorization server accepts.

The assistant opens the xMatix sign-in. The user signs in, ticks the organization or organizations, and approves the access. The connection then appears as Active in the Connections list.

Step 3 — Pin a project to one organization (command-line and editor hosts)

If you belong to several organizations, add the header when you register the server so every call goes to one of them:

claude mcp add --transport http --header "X-Subscription-Key: <key>" xmatix <MCP endpoint URL>

In Claude and ChatGPT, which cannot send headers, ask in the chat instead: "list my organizations", "switch to <organization>", or ask one question about another organization, which uses the per-call organization argument.

Step 4 — Review and disconnect connections

The Connections table on the External assistants page lists Assistant, User, Access (the scopes), Connected, Last used and Status (Active or Revoked). To cut one off, select Disconnect on its row and confirm Disconnect this assistant for this user?. A connection that covered several organizations loses only yours. To cut off every connection at once, switch off Allow external assistants.

Step 5 — Register your own MCP server for Sense agents

1. Open Setup → Sense AI Studio → Configuration → MCP servers and select New MCP server.
2. Fill in the dialog (see MCP server fields) and select Save.
3. If the server needs a secret, select Set credential on its row and paste the API key, bearer token or OAuth client secret.
4. Grant the MCP tools to the agents that should use them: in Sense AI Studio → Configuration → Capabilities, add tool names under MCP tools on a capability, and grant that capability to the agent.

123456 Expand

1. 1

   Label is what administrators see; Name (system key) below is the stable technical identity.

2. 2

   Endpoint is the server's MCP JSON-RPC URL — HTTPS, and never with a secret in it.

3. 3

   Description records what the server exposes and who owns it.

4. 4

   Tool names restrict routing to the listed tools; blank exposes all of the server's tools. This is a routing hint, not authorization.

5. 5

   Authentication: None, API key (custom header), Bearer token or OAuth 2.0 client credentials — the credential is set separately and stored write-only.

6. 6

   Active takes the server in or out of rotation for every agent granted the MCP tools.

Fields

External assistant settings

MCP server fields

The list shows Label, Endpoint, Auth, Credential (only whether one is set) and Status, with Set credential, Edit and Delete on each row.

Business rules

• Turning off Allow external assistants or Allow writes takes effect on the next call and on every token refresh, because the policy is checked on every call.
• A read-only or write-blocked organization hides create_record, update_record and every setup tool that is not read-only, even for tokens that carry the scope.
• The tool list differs by user and by organization. If the capability check itself cannot be evaluated, tools are not capability-filtered for that request rather than hidden.
• A remembered switch_organization into an organization that later refuses the user is forgotten. Calls fall back to the token's default organization.
• Credentials for registered MCP servers are write-only and encrypted. They are never returned, and OAuth client secrets are exchanged for short-lived bearer tokens.
• Every Sense call to a registered MCP server's tool (call_mcp_tool) asks the user for approval before it runs.

Example

A finance controller wants Claude to answer questions over the organization's invoices.

1. An administrator opens External assistants, selects Settings, switches on Allow external assistants, leaves Allow writes off and saves. The header shows Assistants: Enabled and Writes: Read-only.
2. The controller adds a custom connector in Claude with the MCP endpoint URL, signs in and approves. Their row appears in Connections with Access showing xmatix.read.
3. The controller asks "How much did we invoice per month this quarter?". Claude calls describe_entity for Invoice and then aggregate_data grouped by month. The figures cover only the invoices the controller can see in xMatix.
4. The controller asks Claude to correct an invoice's reference. update_record is not in the tool list, so Claude explains that the organization is read-only for assistants.

Training

Practice exercise

In a sandbox organization, turn on external assistants with writes off. Connect Claude Code with claude mcp add, sign in, and ask it to run whoami, then list your open opportunities.

Expected result: whoami shows your user, the sandbox organization and xmatix.read. The opportunities match what you see on the Opportunities list, and the connection appears as Active on the External assistants page. Then select Disconnect on its row: the row's Status changes to Revoked.

Quick reference

• Enable: Setup → Sense AI Studio → Configuration → External assistants → Settings.
• Scopes: xmatix.read, xmatix.write (needs Allow writes), xmatix.setup (needs Allow writes and admin rights).
• Start every session with whoami.
• query_data pages 25 rows by default, 200 at most.
• Filters are expressions such as Status == "Open" && Amount > 1000, not OData.
• record_context gives a record's whole picture in one call.
• Cut off one user with Disconnect, and everyone with Allow external assistants off.
• Register your own tools under Configuration → MCP servers; the secret goes in through Set credential.

Permissions

A user without the Manage AI agents capability does not see the two Setup pages. An assistant used by someone without a permission gets a tool error, or the tool is not listed.

Configuration

• External assistants (Setup → Sense AI Studio → Configuration): the three settings above, the endpoint URL and the connection list. Changes take effect on the next call.
• MCP servers (same menu): registrations, credentials and the Active switch per server.
• Capabilities (Setup → Sense AI Studio → Configuration → Capabilities): the Sense capability grants that decide which data, report, dashboard, dataset and knowledge tools external assistants see, and the MCP tools that let agents reach registered servers. The MCP tools grant is capability-level. An agent granted it can reach every tool on every active registered server, not only the ones named, so register only servers you trust together.
• Knowledge (Setup → Sense AI Studio → Knowledge): the collections search_knowledge searches.

Common problems

The assistant says external assistants are not enabled

The call answered 403 external_assistants_disabled. The administrator has not switched on Allow external assistants, the assistant is not on Approved assistants, or the connection was disconnected. Turn the setting on or add the assistant, then reconnect.

The assistant says I am not a member of this organization

403 tenant_forbidden: the signed-in account has no access to that organization. Sign in with the right account (Not you? on the consent page) or ask an administrator to add you.

Calls fail with "This organization is currently locked"

423 tenant_locked: the organization is temporarily locked. Try again later.

A tool is missing, or the assistant reports an unknown tool

The tool is not offered to this user in this organization. Possible reasons: the scope is missing (writes are off), the organization is read-only, the capability is not granted or licensed, or the setup tools are not available. Run whoami to see the effective scopes. If the host cached an old list, refresh or re-add the connector.

I can't switch to another organization

switch_organization answers that the connection is scoped to a single organization, or that the organization is not one the connection was granted. Reconnect and tick the organization on the consent page. If it is not offered there, its administrator has not enabled external assistants.

The consent page says the form has expired

The sign-in request waited more than 15 minutes or was already used. Start the connection again from the assistant.

A Sense agent can't use my registered MCP server

Check that the server is Active, that a credential is set when its Authentication needs one, and that the agent holds a capability with MCP tools. The user must also approve each call when Sense asks.

Common questions

How is the MCP endpoint different from the data API?

They use the same platform services and enforce permissions the same way, but they serve different consumers. The data API is REST for programs you write, authenticated with your own tokens. The MCP endpoint wraps discovery, queries, reports, knowledge search and governed writes in the Model Context Protocol, so an AI assistant needs only a URL and a sign-in. If you are writing an integration, use the data API. If you are pointing an AI assistant or agent framework at the organization, MCP is the shape it expects.

Can an MCP client modify data?

Only when three things are true together: the administrator has turned on Allow writes, the token carries xmatix.write (or xmatix.setup for configuration), and the user could make the same change in the product. Otherwise the write tools are not even listed. Writes run validation and business rules exactly as in the UI, and they are audited under the user's name. Destructive setup tools are annotated so that the host asks before running them. That confirmation is the host's, not the server's.

Does using MCP expose data beyond the user's permissions?

No. The endpoint requires a real signed-in user. The token is bound to the organizations they approved, and every call is evaluated against that user's security profiles, record security, restriction rules and company scope on the server. The risk to manage is the same as with any AI client: where the assistant sends what it reads. Control which assistants may connect with Approved assistants, and remove access with Disconnect.

Why does the assistant see fewer tools than this page lists?

What an assistant sees is the overlap of its scopes, the organization's Sense capability grants and licences, the organization's read-only state, and whether the setup tools are available. A read-only token hides the write tools. An organization that has not granted a capability (reports, dashboards, knowledge) hides the matching tools. The setup tools need xmatix.setup, and that scope needs the write opt-in. Run whoami first to see what applies.

Does a connected assistant use our AI credits?

No. The assistant reasons with its own model, and the endpoint returns data and performs actions without running Sense or the Setup Copilot. AI credits are spent only by Sense and the Setup Copilot inside xMatix, including when a Sense agent calls one of your registered MCP servers.

Related topics

• Using Sense from Claude, ChatGPT or Claude Code
• The data API
• Troubleshooting the developer surface
• AI Studio: governing Sense in your organization
• Extending Sense with your own capabilities
• How Sense AI is governed