Skip to main content

MCP Server

Beta feature

This is in beta and may be subject to change. Please contact us 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.
  • Have an AI assistant draft changes to an Action Flow, check them, and submit the draft for approval.
  • 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 Manage settings side navigation.
  2. Naviage to MCP > Clients
  3. 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.

Workbench view of the client certificates list
Organisation level settings for MCP Server

Authentication Flow​

The MCP Server uses OAuth 2.0 to authenticate each user individually. After the initial sign-in, a refresh token is issued so the connected client can stay authenticated without the user needing to sign in again for every session.

How long a refresh token remains valid depends on how users authenticate to the Workbench:

  • Username and password - Refresh tokens are valid for up to 30 days.
  • SSO - Users must reauthenticate every 24 hours. This ensures that any role changes made in your external SSO provider are captured promptly.

Independently of token expiry, access can be controlled at any time via:

  • Workbench Roles and Groups - update or remove a user's MCP permissions. See Grant user access for details.
  • Revoking a user's token - organization admins can revoke a connected client's access from the MCP > Clients screen in Organization Settings.

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​

PermissionWhat 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 and change Atomic data through a connected client
MCP Access (Edit)Query and change Atomic data through a connected client
MCP Access (View)Query Atomic data through a connected client, without making changes
Workbench view of the client certificates list
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 to Admin or Edit.
  6. Add MCP Access and set the appropriate level to 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 to Admin or Edit.
  6. Add MCP Access and set the appropriate level to Admin or Edit.
  7. Save the Role.

Step 2: assign the Role to a Group​

  1. Select Groups and open an existing Group, or click Create a new Group.
  2. Add the Role you just created to the Group.
  3. Save the Group.

Step 3: add users to the Group​

  1. 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 for Work (Teams / Enterprise)​

Setup is split into two stages: an admin adds the connector once for the organization, then each user connects their own Atomic Workbench account.

info

Adding an organization connector requires admin access to your Claude for Work organization. You can also see Anthropic's Get started with custom connectors using remote MCP.

Step 1: admin setup​

To make the MCP server available for all users in your Claude organization.

  1. In the Claude admin console, select Connectors under Libraries & Access.
  2. Click Add > Custom > Web. The Add custom connector dialog opens.
  3. In Name, enter a name for the connector. Include your Atomic organization ID or name, because the MCP URL is scoped to a single organization (for example, Atomic - acme-corp).
  4. In Remote MCP server URL, paste your MCP Server URL from the Atomic Workbench.
  5. Click Continue, then follow the remaining prompts to finish adding the connector.

Step 2: user setup​

To connect your own account once an admin has added the connector.

  1. In Claude, navigate to Customize > Connectors. If the connector does not appear immediately, close and reopen the app or refresh the browser.
  2. Find the Atomic connector and click Connect.
  3. Complete the OAuth flow to sign in with your Atomic Workbench account.

Once authenticated, the Atomic tools are available in your Claude chats.

Claude Code​

Run the following command in your terminal, replacing the URL with your MCP Server URL from the Atomic Workbench:

claude mcp add --transport http atomic https://<your-org>.customer-api.atomic.io/mcp/v1

The --transport http flag configures the server to use Streamable HTTP transport. The third argument (atomic) is the name you give the server. You can change it to any name you prefer.

When you next use Claude Code, it will complete an OAuth flow to authenticate with your Atomic Workbench account and authorize access to your organization.

Available tools​

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

Environments and Action Flows​

  • list_environments - lists all active environments in your organization, with their IDs and Workbench links.
  • list_action_flows - lists all Action Flows in an environment, with their IDs, Workbench links, and approval status. Approval status is only returned when approvals are enabled for the environment.
  • get_action_flow_analytics - aggregates analytics events for Action Flows and cards. Filter by Action Flow, card template, customer, event name, and time range. The window can reach back 30 days, and defaults to the last 7.

Building Action Flows​

  • get_action_flow - fetches an Action Flow's full configuration (its steps, triggers, card templates and variables), the draft when one exists, along with whether it is awaiting approval and can still be edited.
  • describe_action_flow_elements - explains how an Action Flow configuration is structured, which steps can follow each step type, and a ready to use outline for each step type.
  • describe_card_elements - explains how a card is structured, which elements can go where, and a ready to use outline for each element type.
  • validate_action_flow - checks an Action Flow configuration without saving anything, listing every problem with the step it belongs to. It also reports whether the configuration is ready to submit for approval, which holds a draft to the stricter checks applied when publishing. It needs edit access to Action Flows, because checking a configuration runs its scripts.
  • update_action_flow_draft - replaces the configuration of an Action Flow's existing draft. The configuration is checked against the same rules the Workbench editor applies, and nothing is saved if any part is invalid. It never creates a draft or publishes one.
  • request_action_flow_approval - submits an Action Flow's current draft for approval, notifies the approval groups, and reports which groups it is now waiting on. The draft must first pass the checks applied when publishing. Asking again while a request is already waiting changes nothing. Approving, rejecting and publishing are always done by people in the Workbench.

Customers and segments​

  • get_user_profile - looks up a single customer profile by external ID, including their tags and custom profile fields.
  • get_user_segment_membership - checks whether a customer is currently a member of a segment.
  • list_segments - lists all customer segments defined in an environment.

Environment configuration​

  • list_custom_events - lists all custom events registered in an environment.
  • list_stream_containers - lists the enabled stream containers in an environment, with their assigned stream and themes, card limit, and the SDK data last seen for each.
  • list_notification_platforms - lists the push notification platforms configured for an environment. Filter by platform ID, app ID or bundle identifier, or platform type.

Theming​

  • list_themes - lists all themes in an environment, and which of them is the default.
  • get_theme - fetches a theme by ID, returning its named variables, the compiled values the SDKs actually render, and the raw payload when the theme uses variables.
  • describe_theme_elements - explains the shape of a theme payload, mapping the components you see in the theme editor to their payload paths and value types.
  • update_theme - changes individual properties of a theme, leaving the rest untouched. Every change is checked against the same rules the theme editor applies, and nothing is saved if any change is invalid.

Documentation​

  • documentation_embedded_search - searches this documentation for material relevant to a question.

Each tool that reads your organization's data respects your Workbench permissions. If you don't have view access to a resource, the tool returns a message indicating no access rather than returning data. documentation_embedded_search is the exception, since it only searches this public documentation.

Tools that make changes​

update_action_flow_draft, request_action_flow_approval and update_theme change your configuration, so they need more than view access:

  • MCP Access at Edit or Admin. With View, the connection is read-only and these tools return a message saying so.
  • Edit access to the resource in that environment: the Action Flow permission for the Action Flow tools, Theme for update_theme.

Most MCP clients ask you to confirm before running a tool that makes changes. A change is made as you, so it is recorded against your Workbench account. In particular, an Action Flow your assistant submits for approval counts as submitted by you, so if your environment prevents the requester approving, you can't approve it yourself.

Every check on an Action Flow configuration includes the step types your environment has disabled, so a draft using one can't be saved or submitted.

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.

Last updated on