Agent access
Let Claude, Cursor or another agent query the companies and datasets you choose.
What an agent key is
An agent key is how an agent such as Claude connects to Gatlas. MCP, the Model Context Protocol, is the open standard agents use to reach outside data, and Gatlas runs an MCP server. Each key opens that server to one agent. A key decides what the agent can read, which datasets it lists, and whether it may change anything, and every call made with it is logged.
Admins and above create keys, on the Agent access page in the sidebar. That page also lists the keys you can see, when each was last used and, for keys made there, its setup link.
Three kinds of key
- Personal key: your own, made when you choose Authorize as your workspace while adding Gatlas to an agent. It acts as you, over everything you can reach, and only you can see its value. Only a personal key can add or rename a company.
- Whole-workspace key: made on the Agent access page with All companies, so it reaches every company in the workspace.
- Guest key: made on the Agent access page for someone else and limited to some companies. It can't approve a brief, see or change an artifact's share link, or delete an artifact. Where it can manage syncs, it never runs a full refresh and waits 10 minutes between manual syncs.
Create a key
Start a new key
Go to Agent access and choose New key.
Name it, and say who it is for
Give it a Key name you will recognize later, such as the person and the agent it is for. Add a Recipient name and Recipient email if Gatlas should email that person the setup instructions.
Choose the permissions
Under Permissions, choose Read-only or Read/write. New keys start as Read/write. See Read-only or read/write below.
Limit what it can see
Under Approved datasets you can limit the key to particular datasets. With one company, the key reads your business and the form does not ask which company.
With several companies, choose under Companies what the key can see:
- All companies: every company in the workspace, including ones added later. If your own access is limited to some companies, this reads All your companies and means those.
- Companies and everything under them: each company you tick, plus every company under it, including ones added under it later.
- Only specific companies: exactly the companies you tick. A company added under one of them later is left out until you tick it too.
If your own access is to specific companies only, the middle choice is not offered, since it would reach companies you don't have.
Important
list_tables, describe_table and query_sql. To keep a company's data away from an agent, leave that company out of the key.Create, and copy what it shows
Choose Create. Gatlas shows the Server URL, the Key and a Setup link for recipient, which is valid for 30 days. You can find the key again later in its Setup instructions on the Agent access page, and the setup link stays there too, even after it expires. Any admin in the workspace can read the key there, so share access to Gatlas with that in mind.
Read-only or read/write
Every key is either Read-only or Read/write, as chosen when it is created, and new keys start as Read/write. You can change it later with Edit access on the key.
- Read-only reads data and sends feedback to Gatlas. It cannot change anything.
- Read/write can also make changes inside the key's scope, for example: create, edit and delete datasets and artifacts, edit briefs, run and schedule brief prompts (each run calls an AI model), and create setup links. Starting a sync or changing its schedule needs sync management, which a key made on the Agent access page does not have. The tools that change something are marked below.
Choose Read-only for anyone who only asks questions. Neither kind can change anything in the tools your data syncs from: no Gatlas tool writes to them.
Tools take your business by default
With one company in a key's scope, the agent never has to name it: tools that act on a company, such as creating a dataset or a setup link, or renaming and describing your business, take that company when none is named. With several companies in scope, a setup link, a dataset from a template or a rename needs one named, and a call without one is refused rather than guessed; a dataset built from SQL with none named is saved with no company, readable only by keys that reach the whole workspace.
Revoke a key
Open the key on the Agent access page and choose Revoke key. It stops working at once. A person who leaves the workspace, or is removed from it, loses the keys they created there.
Every tool an agent can use
An agent sees these tools when it connects. On a Read-only key, the tools marked Changes data are still listed, but the agent is refused if it calls one. The sync tools that need a key that can manage syncs are left out of any other key, as the note under the list explains. Tools marked Changes data need a Read/write key. You never call them yourself: you ask in plain language and the agent picks the tool.
Getting started
get_agent_context- Loads the rules for working with your data, the companies in reach and any freshness warnings. Agents call it first.
get_help- Explains how to use Gatlas: where to start, which datasets and briefs to set up, and what to do when a question goes wrong.
submit_feedback- Sends feedback about Gatlas, such as a bug or missing data, to the Gatlas team.
list_companies- Lists the companies this key can see.
create_company- Adds a company to your workspace, so its sources and datasets have a home. Only after you confirm its name.
edit_company- Renames a company or rewrites its description and AI context. Only after you confirm the change.
Sources
list_connections- Lists each company's sources with their sync schedule, status and how fresh the data is.
get_sync_status- Shows sync health for every source this key can see. Needs a key that can manage syncs.
list_sync_runs- Lists the latest sync runs and how each one went. Needs a key that can manage syncs.
trigger_sync- Starts a sync of one source now. Needs a key that can manage syncs.
edit_sync_schedule- Changes how often a source syncs by itself.
mint_setup_link- Creates a setup link that someone opens with no Gatlas login, to connect one or more tools to a company or reconnect one. Only after you ask for one.
Library
list_tables- Lists the raw synced tables for each company, with their columns.
describe_table- Describes one raw synced table: its columns, row count and date range.
query_sql- Runs a read-only SQL query over your datasets and synced tables, for totals and joins or questions no dataset covers.
search_company_files- Searches the synced files, such as contracts and board packs, when no brief covers the question.
get_company_file- Reads the text of one synced file, a page at a time.
Definitions
list_datasets- Lists every approved dataset this key can query.
search_datasets- Finds approved datasets by keyword, company or topic.
describe_dataset- Reads a dataset's description, AI context and column notes before querying it.
query_dataset- Reads rows from an approved dataset, with filters. The usual way to get numbers.
create_dataset- Creates and approves a dataset from a catalog template or from SQL, with its description and AI context.
edit_dataset- Changes a dataset's name, SQL, AI context or column notes.
delete_dataset- Permanently deletes a dataset. Without a confirmation it only reports what would be affected.
list_briefs- Lists the briefs this key can read, such as company overviews and board summaries.
get_brief- Reads one brief, its past versions and the files behind it.
edit_brief- Updates or approves a brief and keeps the previous text as a version.
list_brief_prompts- Lists the prompts that write and refresh briefs.
create_brief_prompt- Creates a prompt that writes a brief from your files, briefs and datasets, on a schedule or on demand.
edit_brief_prompt- Changes a prompt's instructions, inputs, brief or schedule.
run_brief_prompt- Runs a prompt now, as a preview or for real.
Artifacts
list_artifacts- Lists the listed artifacts: dashboards, documents and decks built on your datasets.
list_components- Lists the saved charts, tables and text blocks artifacts can reuse, and how many artifacts use each one.
describe_artifact- Reads one artifact's charts, tables and text, the datasets they use and its share link.
describe_component- Reads one saved chart, table or text block and lists the artifacts that use it.
create_artifact- Builds a dashboard, an A4 document or a slide deck from charts, tables and text over approved datasets.
create_component- Saves one chart, table or text block as a saved component, so any artifact can reuse it.
create_edition- Makes a numbered edition of a deck or document: a frozen copy at its own link, which an admin can withdraw.
edit_artifact- Changes an artifact's contents, layout or share link.
edit_component- Changes a saved chart, table or text block in every artifact that uses it.
delete_artifact- Permanently deletes an artifact, its share link and its editions. Without a confirmation it only reports what would be affected.
delete_component- Removes a saved chart, table or text block that no artifact uses anymore. Without a confirmation it only reports what would be affected.
The sync tools, sync status, sync runs, starting a sync and its schedule, need a key that can manage syncs, which the Agent access page does not offer yet. To get one, write to team@gatlas.ai.