Connect an AI client with MCP

Connect Claude Code, Claude Desktop, ChatGPT, Codex, 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 ChatGPT or Codex

The ChatGPT desktop app (which includes Codex) can use Control as an MCP server.

1. Download and install the ChatGPT desktop app, which includes Codex. If your organization manages software installs, ask your IT team first.
2. Sign in, or create an OpenAI account.
3. Open ChatGPT → Settings… from the menu bar (⌘ , on macOS).

4. Go to Plugins → MCPs. You can type mcp in the settings search to find it.

5. Select Add → Add MCP Server in the top-right corner and fill in:

   Field	Value
   Name	A name you recognize, for example Control-MCP
   Type	Streamable HTTP
   URL	The workspace server URL from Control, for example https://api.control.dev/api/mcp?tenant=<tenant-id>

6. Select Save. Control-MCP appears in the server list with an Authenticate button.

7. Select Authenticate and sign in to Control in the browser window that opens.

You can now ask ChatGPT or Codex questions in chat, and it calls Control through MCP.

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. Control validates it against your workspace memberships and rejects the connection if it does not match.
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.

Control rejects authorization when the URL’s ?tenant=<tenant-id> points to a workspace that the signed-in user is not a member of. Control does not fall back to another workspace you belong to. Re-copy the URL from the MCP Server page in the intended workspace, or sign in with an account that is a member of that workspace.

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

• Correct counterparty assignments
• Troubleshoot Control MCP
• Use skills with Control MCP