Connect an AI client with MCP

Connect Claude Code, Claude Desktop, or another MCP client to your Control workspace.

Control’s Model Context Protocol (MCP) server lets compatible AI clients query financial statements, cash flow, transactions, mappings, dimensions, and connector data using your existing Control permissions.

Before you start

You need:

• access to the Control workspace you want the client to query;
• an MCP client that supports remote HTTP servers and OAuth; and
• the workspace-specific server URL from in Control.

Copy the URL from Control instead of constructing it manually. It includes the current tenant when available, which prevents ambiguity for users with access to several workspaces.

Connect Claude Code

Use the URL shown in Control:

claude mcp add --transport http --scope local control-mcp '<workspace-server-url>'

Claude opens a browser so you can sign in and authorize the connection. In this command, --scope local controls where Claude saves its configuration; it is not an OAuth permission scope.

If your workspace requires a pre-registered OAuth application, add the client ID shown in Control:

claude mcp add --transport http --scope local --client-id '<client-id>' control-mcp '<workspace-server-url>'

Connect a desktop or other MCP client

Add Control as a remote HTTP MCP server. Clients that accept JSON configuration commonly use this shape:

{
  "mcpServers": {
    "control": {
      "url": "<workspace-server-url>"
    }
  }
}

The client should discover Control’s OAuth protected-resource metadata and complete authorization code with PKCE. Use URL-only Dynamic Client Registration unless your administrator has configured a pre-registered client ID.

How access works

Layer	Behavior
Sign-in	OAuth identifies the Control user and supports refresh tokens.
Workspace	The tenant query parameter pins the connection to a workspace when needed.
Session	A client can request read or write access during MCP initialization.
Tools	Read-only sessions do not receive write tools, and the server enforces the access level again when a tool runs.
Product access	Tenant membership, the user’s role, and enabled workspace features still apply.

OAuth scopes such as profile, email, and offline_access identify the user and keep the connection alive. They do not grant individual financial tools or datasets.

Discover available tools

After connecting, ask the client to refresh its tool list. Control exposes tools for areas such as:

• group and entity financial statements;
• cash-flow analysis;
• transaction browsing and evidence;
• accounts, dimensions, layouts, currencies, and accounting settings; and
• Google Sheets and Excel connector setup and synchronization.

The MCP tools/list response is the source of truth for the tools available to the current user. Reconnect or refresh the list after Control adds or changes tools.

Ask useful questions

Start with questions that state the reporting scope and period clearly:

• “Show consolidated revenue by month for January through June 2026.”
• “Why did personnel costs change between May and June? Show the supporting transactions.”
• “Compare operating profit for Entity A and Entity B.”
• “Which group account is local account 4000 mapped to?”

When you name a subsidiary or legal entity, the client can select entity-specific tools. Otherwise, financial review defaults to group-wide data.

Troubleshooting

The client shows no tools or an old tool list

Reconnect the server or ask the client to run tools/list again.

Control cannot choose a workspace

Copy the server URL again from the MCP Server page. It should include ?tenant=<tenant-id> for multi-workspace users.

Authorization reports an authorized-party error

Ask a Control administrator to confirm that MCP Dynamic Client Registration is enabled for the environment. If the workspace uses a pre-registered client, use its displayed client ID.

A write operation is missing

The session may be read-only, the user may not have permission, or the required workspace feature may be disabled. Reconnect with the intended access level and confirm the user’s Control role.

Keep access tokens and refresh tokens inside the MCP client. Never paste tokens or client secrets into documentation, chat messages, spreadsheets, or browser-visible configuration.

Related content

• Troubleshoot Control MCP
• Use skills with Control MCP