MCP servers¶

MCP (Model Context Protocol) connects Adverity Atlas to the other tools your team uses. It works in both directions.

Connect external tools to Adverity Atlas: Register a server such as Jira or Slack, and Adverity Atlas can use its tools in chat and in automations: reading a ticket, posting a message, pulling live data
Use Adverity Atlas from your own tools: Adverity Atlas is itself an MCP server, so an IDE or AI assistant (such as Claude Desktop) can query your data through the same glossary and knowledge layer

Most of this page covers the first direction, connecting external servers, which is where setup and credentials matter. The second direction is covered under Using Adverity Atlas from your own tools.

Available servers¶

Adverity Atlas ships a catalogue of ready-to-configure servers, so common tools connect without hand-entering their endpoint and transport. Each is set up the same way: pick it when adding a server, then authorize. The table shows what each one covers and how it authenticates.

Server	What it does	Authentication
Adverity Connect	Query your Adverity datastreams, connectors, and connected data sources	OAuth 2.1
Asana	Read and manage Asana tasks and projects	OAuth 2.1
Atlassian (Jira / Confluence)	Search Jira issues and Confluence pages	OAuth 2.1
GitHub	Browse repos, issues, and pull requests	OAuth 2.1
Google Drive	Search and read Google Drive files, folders, and documents	OAuth 2.1 (service config)
HubSpot	Query HubSpot contacts, companies, deals, and tickets	OAuth 2.1 (service config)
Linear	Query and update Linear issues and projects	OAuth 2.1
Meta Ads	Query Meta (Facebook/Instagram) ad accounts, campaigns, and insights	OAuth 2.1
Mixpanel	Query Mixpanel events, funnels, and retention. Defaults to the EU region, switch the URL for US (mcp.mixpanel.com) or IN (mcp-in.mixpanel.com)	OAuth 2.1
Navattic	Query demo analytics; browse and edit projects, flows, and share links	OAuth 2.1
Notion	Search and edit Notion pages and databases	OAuth 2.1
OpenWeather	Query current weather, forecasts, and historical conditions by location	Bearer token
Sentry	Inspect Sentry issues and error events	OAuth 2.1
Slack	Read channels and post messages. Set the URL of your hosted Slack MCP server	Bearer token
Stripe	Query Stripe customers, charges, and invoices	Bearer token
Zoom	Query Zoom meetings, recordings, and users	OAuth 2.1 (service config)

Servers marked service config use an OAuth client an admin registers under Service configs; the rest register their client automatically.

You are not limited to the catalogue. Choose Custom server when adding a server, described as “Enter the URL and auth manually”, to register any MCP-compatible server by its URL, whether an internal server or one not in the catalogue. It is configured the same way as a catalogue server, with the auth types and scopes below.

Important

Available on demand. Connecting external MCP servers is enabled per organization. If you do not see the option, ask your Adverity account team to turn it on. Once it is on, you get the catalogue above and can add custom servers yourself.

Two ways to authorize a server¶

Every server has an auth scope that decides who owns its credentials and, crucially, where they are set up. This is the part most easily missed.

Organization-wide¶

An admin authorizes the server once, and everyone in the organization can use it. Best for shared, service-account style access.

Who sets it up:: An admin, under Settings > Integrations
Who can then use it:: Everyone in the organization

Per-user¶

Each person authorizes their own connection, so actions run as that user and respect their own permissions in the external tool. Best when access should follow the individual.

Who sets it up:: Each user, under Profile > MCP Connections
Who can then use it:: Only that user

Note

A per-user server is not usable until you authorize it yourself. If the Atlassian (Jira) server is configured per-user, its tools stay unavailable to you in chat until you set up your own credentials in Profile > MCP Connections, even after an admin has enabled the server for the organization.

A per-user server can only be used in Chat. An automation runs on a schedule with no one signed in, so it can only use organization-wide servers.

Setup¶

The steps depend on the scope above.

Organization-wide (admin)¶

Add the server: From the catalogue or by URL
Choose the auth type: None, bearer, or OAuth 2.1
Verify the connection: The exposed tools are listed

In detail:

Go to Settings > Integrations and add an MCP server, from the catalogue or by URL.
Choose the auth type: none, a bearer token or static header, or OAuth 2.1. OAuth servers that do not support dynamic client registration use a service config for the client app; the rest register the client automatically.
Under Allowed consumers, tick Chat, Automation, or both. This decides which agents may call the server’s tools. A catalogue server starts with both ticked; a custom server starts with Chat only.
Provide the credentials, then verify the connection. Adverity Atlas lists the tools the server exposes.

Per-user (each person)¶

Open MCP Connections: From your profile
Authorize: Your own connection
Use its tools: In your conversations

In detail, open Profile > MCP Connections, find the server, and authorize your own connection. This is a one-time step per server.

Registering and enabling servers requires the Admin role. Authorizing a per-user connection is something each user does for themselves.

When a server’s tools do not show up in chat¶

A registered server is not automatically a usable one: several conditions have to hold before the agent can call it, and the most common support question is which one is missing. MCP diagnostics answers that directly.

Open Settings > Integrations > MCP Servers, then Diagnose in the row’s actions menu. The panel opens on a verdict, either Visible to the chat agent, with the number of tools it exposes, or Hidden from the chat agent, listing what is blocking it.

Below the verdict, Gates shows each condition and whether it is met:

Gate	What it means
MCP servers enabled	Outbound MCP is enabled for your organization
Enabled	The server is switched on, not left registered but inactive
Verified	Adverity Atlas has connected to it successfully at least once
‘chat’ in consumers	Chat is among the consumers allowed to use this server
Credential connected	The authorization it needs has been completed

Discovered tools then lists every tool the server exposes, each named with the server slug as a prefix, and badged enabled or filtered according to the tool scoping an admin has applied. When nothing has been discovered yet, the panel says so and points you at Verify.

Note

Adverity Atlas skips any single tool whose definition the AI model would reject, for example a tool name with characters other than letters, digits, _, and -, or a tool whose inputs are not described as an object. The agent cannot call that tool, but the server’s other tools keep working. Discovered tools still lists a skipped tool, so a tool that shows as enabled there and is never used may be one of these.

Two actions sit at the top: Re-verify reconnects and re-reads the server’s tool list, and Refresh re-runs the diagnostic. The rest of the panel is read-only; the conditions themselves are changed on the server’s own Edit panel or in your profile, depending on the gate that failed.

Tip

Reach for Diagnose before Verify. Verify only tells you the server answered; the gate list tells you why the agent still cannot see it, which for a per-user server is usually the missing credential rather than anything wrong with the server.

Using Adverity Atlas from your own tools¶

Adverity Atlas is itself an MCP server, so a client that speaks MCP, an IDE or an AI assistant such as Claude Desktop, can reach your data through the same glossary and knowledge layer that answers in Chat. Nothing is installed and no key is copied around: the address is the whole configuration.

Add the server: In your client, by URL
Authorize: Sign in and pick the account
Use the tools: From your own client

In detail:

In your MCP client, add a server whose URL is the /mcp path on your Adverity Atlas address, for example https://<your-atlas-host>/mcp. The client discovers the rest of the configuration from there, which is why there is nothing else to enter.
The client registers itself and sends you to an Authorize Application page. It names the client, lists the Requested permissions, and asks you to Select account. Select workspace is optional and defaults to All workspaces, so narrow it when the client should only reach one team’s data.
Click Authorize. The client is connected and its tool list fills in. Deny cancels and returns the client empty-handed.

Authorization is OAuth 2.1, granted against three scopes: read, write, and admin. You are authorizing as yourself, so the connection carries your own membership and roles.

Connect a local client (stdio)¶

For a client that launches a local process, the Adverity CLI runs the server over stdio:

adverity mcp serve --tenant <your-organization>

It authenticates with an API key (issued under Settings > Service accounts), adverity login, or the ADVERITY_API_KEY environment variable. With API-key auth --tenant is required; with adverity login it is auto-detected. The Claude Desktop configuration looks like:

{
  "mcpServers": {
    "adverity": {
      "command": "uv",
      "args": ["run", "adverity", "mcp", "serve", "--tenant", "my-company"]
    }
  }
}

What the client can do¶

The tools come from the same registry the agent uses in Chat, so an external client works through the semantic layer rather than against raw tables:

Atlas exposes 66 tools across 8 capabilities:

Capability	Tools
Workspaces and account (11)	`create_workspace`, `get_task_execution`, `get_tenant`, `get_workspace`, `invite_member`, `list_approvals`, `list_members`, `list_tenants`, `list_workspaces`, `select_workspace`, `vote_approval`
Data sources and schema (9)	`call_connector_operation`, `describe_asset`, `get_asset_profiles`, `get_joinable_assets`, `get_schema`, `list_connector_operations`, `list_datasources`, `search_metadata`, `validate_aggregation`
Glossary, knowledge, and metrics (12)	`capture_brand_design_manual`, `create_glossary_concept`, `find_fields_by_role`, `get_brand_design`, `get_naming_convention`, `list_glossary_concepts`, `list_metrics`, `query_metrics`, `read_knowledge`, `research_brand_design`, `resolve_concept_to_fields`, `search_knowledge`
Files (3)	`list_workspace_files`, `load_file`, `query_file`
Artifacts, apps, and outputs (17)	`create_csv`, `create_data_app`, `create_markdown`, `create_presentation`, `create_slide_master`, `delete_artifact`, `edit_artifact`, `edit_presentation`, `get_artifact_source`, `list_artifacts`, `list_slide_masters`, `preview_data_app`, `preview_presentation`, `rename_artifact`, `restore_artifact_version`, `test_data_app_query`, `update_data_app_queries`
Automations (10)	`create_automations`, `create_custom_automation`, `get_automation`, `get_automation_runs`, `list_automation_templates`, `list_automations`, `preview_automation_update`, `preview_custom_automation`, `run_automation_now`, `update_automation`
Product documentation (3)	`list_documentation_pages`, `read_documentation`, `search_documentation`
Support (1)	`create_support_ticket`

A few tools stay inside a conversation and are not offered over MCP, notably raw SQL execution and the in-conversation DataFrame analysis that builds on it. Where the declarative metric layer is switched on for your organization, the client can query approved metrics by name instead, see Measures.

Note

Every tool checks the same permission over MCP as it does in the product, against the account you authorized with. An external client can never do more than you can, and a Viewer’s client stays read-only. A small set of read and setup tools (listing organizations and workspaces, select_workspace, and the documentation tools) needs no permission.

Governance¶

Logged activity: MCP tool calls are logged with the server and tool name; changes to the servers themselves (registering, editing, removing) are recorded in the audit trail with the actor
Encrypted credentials: Tokens are stored encrypted and never exposed in conversations
Tool scoping: An admin controls which tools on a server are enabled, and which agents may use them

What’s next?¶

Chat: where MCP tools are used, alongside warehouse data
API: call Adverity Atlas from a script or backend service instead of an AI assistant
Automations: scheduled runs that can call organization-wide MCP tools
Service configs: the OAuth client credentials an admin sets up for a server
Settings & Admin: the Integrations area where servers are registered