MCP Server

Preview feature

This is in preview and may be subject to change. Please contact us to have this feature enabled in your organization or to provide feedback.

The Atomic.io MCP Server lets you connect AI assistants and developer tools that support the Model Context Protocol (MCP) to your Atomic organization. Once connected, these tools can query your Atomic data using natural language without leaving your editor or AI assistant.

Example use cases

• Ask an AI coding assistant to list all Action Flows in a given environment while building an integration.
• Use Claude or VS Code Copilot to look up a customer's profile and tags during debugging.
• Query Action Flow analytics for a specific flow using a conversational prompt.
• Explore which environments exist in your organization without opening the Workbench.

Enable the MCP Server

Only organization members with permission to manage organization preferences can enable the MCP Server.

1. In the Atomic Workbench, open Organization Settings from the account settings side navigation.
2. Select OAuth Clients from the left menu.
3. Under MCP Server, toggle Enable MCP Server on.

Once enabled, your organization's MCP Server URL is displayed. Copy this URL as you will need it when configuring your MCP client.

Organisation level settings for MCP Server

Grant user access

After enabling the MCP Server, individual users need two permissions before they can fully use the MCP Server:

• MCP Registration — allows a user to register and connect an MCP client to your organization.
• MCP Access — allows a user to query Atomic data through a connected MCP client.

Both permissions must be assigned for a user to connect a client and retrieve data.

Access is controlled through three layers:

• Permissions are added to Roles.
• Roles are added to Groups.
• Users are assigned to Groups.

To give a user MCP access, ensure they belong to a Group whose Role includes both MCP permissions.

For more detail on permission levels, see the Permissions guide.

MCP permission levels

Permission	What it allows
MCP Registration (Admin)	Enable or disable the MCP Server at the organization level, and register MCP clients
MCP Registration (Edit)	Register and connect MCP clients
MCP Access (Admin)	Manage MCP access settings and query Atomic data through a connected client
MCP Access (View)	Query Atomic data through a connected client

MCP permissions available

Add the MCP permissions to an existing Role

Use this approach if you have an existing Role and Group that already covers the right set of users.

1. In the Atomic Workbench, navigate to Organization > Workbench Members.
2. Select Roles.
3. Open the Role you want to update.
4. Search for MCP in the permissions list.
5. Add MCP Registration and set the appropriate level — Admin or Edit.
6. Add MCP Access and set the appropriate level — Admin or Edit.
7. Save the Role.

All users in any Group assigned this Role will now have MCP access.

Create a new Role with the MCP permissions

Use this approach if you want to be more selective — for example, to grant MCP access to a subset of users who don't share a Role with others.

Step 1 — Create the Role:

1. In the Atomic Workbench, navigate to Organization > Workbench Members.
2. Select Roles, then click Create a new Role.
3. Give the Role a name (for example, MCP Users).
4. Search for MCP in the permissions list.
5. Add MCP Registration and set the appropriate level — Admin or Edit.
6. Add MCP Access and set the appropriate level — Admin or Edit.
7. Save the Role.

Step 2 — Assign the Role to a Group:

8. Select Groups and open an existing Group, or click Create a new Group.
9. Add the Role you just created to the Group.
10. Save the Group.

Step 3 — Add users to the Group:

11. Open the Group and add the users who should have MCP access.

Users added to this Group will now be able to connect an MCP client and query data from your organization.

Connect an MCP client

The MCP Server uses OAuth to authenticate. When you add it to a client for the first time, you will be redirected to sign in with your Atomic Workbench account and authorize access to your organization.

VS Code (GitHub Copilot)

1. Open the Copilot panel in VS Code and select the Agent mode dropdown (the model picker at the bottom of the chat input).

2. Click Add MCP Server, then choose HTTP.

3. Enter your MCP Server URL when prompted and give the server a name (e.g. atomic).

   VS Code saves this to your workspace .vscode/mcp.json, which will look like:

   {
     "servers": {
       "atomic": {
         "url": "https://<your-org>.customer-api.atomic.io/mcp/v1",
         "type": "http"
       }
     }
   }

4. Click Connect - VS Code will open a browser window to complete the OAuth flow. Sign in with your Atomic Workbench account and authorize access.

5. Once connected, the Atomic tools will appear in the Copilot agent tool list.

Microsoft Copilot Studio

1. Open Copilot Studio and select your agent.
2. Select the Tools page, then click Add a tool.
3. Select New tool, then choose Model Context Protocol.
4. Fill in the details:
   • Server name - for example, Atomic
   • Server description - for example, Access Atomic Action Flows and customer data
   • Server URL - paste your MCP Server URL from the Atomic Workbench
5. Under Authentication, select OAuth 2.0, then choose Dynamic discovery.
6. Click Create. Copilot Studio will discover the authentication configuration automatically from the server.
7. Click Add to agent to finish.

When a user runs the agent for the first time, they will be prompted to sign in with their Atomic Workbench account to authorize access.

Claude

1. Open Claude Settings and navigate to Integrations.
2. Add a new integration using your MCP Server URL.
3. Complete the OAuth flow when prompted.

Available tools

Once connected, your AI assistant has access to the following Atomic tools:

• list_environments - lists all active environments in your organization.
• list_action_flows - lists all Action Flows in a given environment.
• get_action_flow_analytics - retrieves analytics events for an Action Flow (up to 7 days of data).
• get_user_profile - looks up a customer's profile, active tags, and custom fields.

Each tool respects your Workbench permissions. If you don't have view access to a resource, the tool will return a message indicating no access rather than returning data.

One organization per connection

Each MCP Server connection gives access to a single Atomic organization. If you have access to multiple Atomic organizations, add a separate MCP server entry for each one using that organization's unique MCP Server URL.

Troubleshooting

I don't see the Enable MCP Server toggle.

You may not have permission to manage organization preferences. Ask your Atomic organization owner to enable the MCP Server or to grant you the required permission.

I can authenticate but receive an authorization error when connecting an MCP client.

Your account may be missing the MCP Registration or MCP Access permission (or both). Ask your organization owner to add both permissions to a Role in a Group you belong to. See Grant user access for details.

VS Code shows an authentication error when connecting.

If the connection fails after a previous successful authentication, your cached credentials may be stale. Open the VS Code Command Palette and run Authentication: Remove Dynamic Authentication Providers, then reconnect and complete the OAuth flow again.

The AI assistant reports no access to a tool.

Each tool checks your Workbench permissions before returning data. If you lack view access for a resource in a given environment, the tool returns a no-access message. Contact your organization owner to review your role and permissions.

I enabled the MCP Server but the URL is not visible.

Try refreshing the page. The URL is displayed after the toggle is saved successfully.

A registered client shows "MCP Disabled" status.

This means the MCP Server toggle has been turned off at the organization level. Any registered OAuth clients lose access when the MCP Server is disabled. Re-enable the toggle to restore access.