Connect an AI agent to Omniscope with the MCP server

Point Codex or Claude Code at an Omniscope project and it can build in it: prepare the sources, add and wire blocks, run the workflow, create a Report, then look at what came back and fix what it got wrong. What you get at the end is an ordinary Omniscope project. You open it, inspect the workflow, change a block, rerun it. Nothing is hidden in generated code you would have to reverse-engineer.

As an example we built a working Customer Success application this way in a single Codex session -  the finished project is public, and Omniscope as a tool for AI agents explains where this sits alongside the AI features that run inside Omniscope.

This article covers the setup: the endpoint, the key that authenticates it, and the configuration for each client.

Before you start

This is Canary functionality for now, we'll soon integrate it in the latest verified Preview build.

• A Canary build. with the MCP endpoint and the API key mechanism.
• Workflow AI switched on. Admin → Labs → Experimental features → tick Workflow AI, then Save. 
• An Enterprise licence that includes automation. MCP and the REST API are covered by Automation capabilities. 

The project is the endpoint

There is no server-wide MCP URL. Each project exposes its own, formed by appending /api/dm/ai/hl/mcp to the project's address:

https://your-server.example.com/Folder/Project.iox/api/dm/ai/hl/mcp

That is deliberate. The unit of access is the project, so a key you hand to an agent reaches the project you pointed it at and inherits that folder's permissions.

Two sibling doors sit alongside it, over the same tools, for callers that would rather not speak MCP:

Discovery is part of the protocol, so you do not have to tell the agent what Omniscope can do. It asks, and gets the current tool list back.

Create a key for the agent

An API key is a long-lived credential for a machine. It is not a login: presenting one will not sign the agent into the Omniscope interface, and it is honoured only on the programmatic routes above.

Open the project list, click your avatar in the top right, choose Edit permission, and work down the dialog.

Make a group for your agents. Under Groups, click Add Group and name it something you will recognise later - MCP will do.

Give it the API permission. Set Group permissions to Custom, click Configure, and set Full project access via APIs to Yes.

That permission opens the door and nothing else. As the tooltip says, it grants nothing on its own: whether the agent may read, or also write, is still decided by Project viewer and Project editor in the same panel. For an agent that will author a project, give it Project editor. For one that should only read and report, leave it at viewer.

Add the key. Under Group authentication, click Add authentication mechanism and choose API keys.

Click Add. Omniscope generates a key in your browser, hashes it, and sends only the hash to the server. It looks like this:

omsk_ADYMeQQmn2A_ro1FVx-IO4DrdqrLfe_nCsw68nlMpKs

Copy the key before you close the dialog. It is stored as a BCrypt hash, so nobody =including you, including us - can recover it afterwards. Lose it and you generate a new one, which stops the old one working.

Then click Save. The dialog will not let you save a key that was not hashed properly, so a successful save means the credential is sound.

To rotate later, use the regenerate button on the row. The key's identity stays the same, so the access log still attributes past activity to it, while the credential itself changes and the old value stops working immediately.

Configure the client

Codex

Add a [mcp_servers.…] table to ~/.codex/config.toml, or use .codex/config.toml inside a project:

[mcp_servers.omniscope] url = "https://your-server.example.com/Folder/Project.iox/api/dm/ai/hl/mcp" bearer_token_env_var = "OMNISCOPE_MCP_TOKEN"

Set OMNISCOPE_MCP_TOKEN to the key in your environment. Codex sends it as the Authorization header for you, and the key stays out of the config file and out of version control.

The IDE extension exposes the same settings under the gear menu → MCP servers.

If you would rather set the header directly, http_headers takes static values and env_http_headers reads them from the environment:

[mcp_servers.omniscope] url = "https://your-server.example.com/Folder/Project.iox/api/dm/ai/hl/mcp" env_http_headers = { Authorization = "OMNISCOPE_MCP_AUTH" }

Run codex mcp list to check it registered, and /mcp inside the Codex TUI to see it connected.

Claude Code

One command:

claude mcp add --transport http omniscope \  https://your-server.example.com/Folder/Project.iox/api/dm/ai/hl/mcp \  --header "Authorization: Bearer omsk_…"

If you configure it as JSON instead — in .mcp.json or ~/.claude.json — the entry needs "type": "http". A url with no type is treated as a configuration error rather than being guessed at.

Claude Desktop

Claude Desktop connects to remote MCP servers through Customize → Connectors → Add custom connector, which takes the server URL and, under Advanced settings, an OAuth Client ID and Secret. There is no field for a static header, so an Omniscope API key cannot be used here.

Use Codex or Claude Code for the API key route. If you need Claude Desktop specifically, authenticate through Omniscope's OpenID Connect integration instead, which is OAuth and does fit the connector model.

Tell the agent what you want, not how to click

Once connected, the agent discovers the tools itself. You give it an objective:

Connect to the Omniscope project on the MCP server. Look at what is already in the workflow, then load customers.csv and renewals.csv, join them on account ID, work out which renewals are at risk in the next 90 days, and build a Report with a summary view and a table I can filter by owner. Run the workflow and check the output before you tell me you are done.

Being able to say check the output is the part that changes how this feels. The agent runs the workflow through the same execution path the interface uses, reads the result, and corrects itself. 

In our experiments it went further: where something was not exposed as a tool yet via the MCP or API, Codex drove the Omniscope interface as a person would.

Running against Omniscope on your own machine

The guidance above mainly applies when an agent connects to Omniscope over a network. When you are running Omniscope on your mchine and connecting to it from the same machine, the setup is intentionally a little different.

A local project has an address such as:

http://127.0.0.1:24679/Project.iox/api/dm/ai/hl/mcp

This is the simplest way to get started with MCP locally.

By default, requests from localhost use Omniscope’s Local desktop experience. This mode is designed for applications running on your own computer and gives them the same broad project and folder access you would expect when using Omniscope as a desktop application.

As a result, when connecting through localhost:

• An API key is not required or checked, even if one has been configured.
• The Full project access via APIs setting does not restrict the local connection, because the Local desktop experience takes precedence.

This is intentional behaviour for local desktop use. It allows Omniscope to work conveniently with other applications running on the same machine without requiring additional authentication for every local request.

If you prefer to use Omniscope as a network-accessible service, you can instead enable the external web server and connect through the address associated with the machine’s network adapter. In this configuration, the normal API authentication and permission settings apply, including API keys and project-access controls.

For server or production-style deployments, where you want all connections to follow those network authentication and permission rules, disable Local desktop experience under Admin → Web server → Network.

In short, you can choose the setup that suits your use case:

• Local desktop use: convenient access for applications running on your own machine, with full local permissions.
• External/network use: access through the external web server, with API keys and configured permissions enforced.

If you do not want MCP to be available at all, disable workflow Ai under Admin → Labs. This disables the MCP endpoint for both local and remote connections.