Skip to content
Help center

Connect your agent

Someone gave you an agent key: add Gatlas to your agent in about a minute and ask a first question.

What you have been given

Someone you work with uses Gatlas to bring its business's data together, and has given you an agent key to it. An agent key is how an agent such as Claude connects to Gatlas: with it, your agent can answer questions from that data directly. You do not need a Gatlas account.

You will usually have received a setup link. It opens a page titled with the workspace's name, such as Connect Acme Holdings to your agent, with your key, what the key can see, whether it is Read-only or Read/write, and a tab for each agent. Follow the tab for yours; the steps below are the same. If you were sent a key instead, keep it private: anyone who has it gets the same access, including changes if the key is read/write.

Add Gatlas to your agent

Pick the agent you use. You only need one of these.

claude.ai or Claude Desktop

On your setup page, choose Add to Claude: Claude opens its connector form with Gatlas filled in, and you choose Add. To add it by hand instead, go to Settings, Connectors and choose Add custom connector. Paste this server URL and choose Add:

https://www.gatlas.ai/api/mcp

Choose Connect. A Gatlas page opens in your browser. If you started from Add to Claude on your setup page in the same browser, choose Authorize with your setup link. Otherwise paste your key there and choose Authorize. The key goes to a Gatlas page, never into Claude's chat. To stop using it, remove the connector in Claude. To cut off the key itself, ask whoever gave it to you, or another admin there with the same access, to revoke the key.

Claude Code

Run this in your terminal, with your key in place of YOUR_KEY:

claude mcp add --transport http gatlas https://www.gatlas.ai/api/mcp --header "Authorization: Bearer YOUR_KEY"

Cursor and other MCP clients

On your setup page, Add to Cursor opens Cursor and installs Gatlas with your key included. To add it by hand, in Cursor open Settings, MCP, Add new server, and paste this configuration with your key in place of YOUR_KEY. You can also add it to ~/.cursor/mcp.json. Other clients that support MCP take the same settings.

{
  "mcpServers": {
    "gatlas": {
      "url": "https://www.gatlas.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_KEY"
      }
    }
  }
}

Note

Gatlas then appears among your agent's connectors. If it does not, restart the agent.

What to ask

Start a new chat and paste this. The agent reports what it can answer from your data so far, and what is still to set up:

Prompt for your agent
Based on what you know about me and my business, show me what Gatlas can do for us and help me set up what is missing.

In Claude Code, run /mcp__gatlas__gatlas_get_started instead. After that, ask in plain language. The agent finds the right data by itself. Some questions for once datasets are in place:

  • "What datasets are available to me?"
  • "What was revenue last quarter?"
  • "Show me the top 10 customers by order value."
  • "Compare monthly revenue across the last six months."
  • "Is any of the data out of date?"

The agent only sees the data and datasets your key covers, and when it covers one company, tools take that company without your naming it. Whether it can also change anything, such as creating a dataset, depends on the permissions the key was created with; see Read-only or read/write.

Use more than one workspace in Claude

Claude takes one connector per server URL, so a second Gatlas workspace needs its own address. Add ?workspace= and a name of your choice to the end of the URL, such as https://www.gatlas.ai/api/mcp?workspace=acme. Gatlas ignores the name: the key you log in with decides which workspace the connector reads.

  • Open the setup link for the second workspace and choose Add to Claude.
  • In Claude's form, name the connector after the workspace, such as Gatlas Acme Holdings, and add ?workspace=acme to the end of the URL. Choose Add.
  • On the Gatlas page, choose Authorize with your setup link, or paste that workspace's key. A key from your first workspace would connect the first workspace again, under the new name.

To check, ask each connector which business it can see. In Claude Code or Cursor, add a second entry under its own name, with the second workspace's key.

If something goes wrong

  • Gatlas is not listed, or its tools are missing. Check that the server URL is exactly https://www.gatlas.ai/api/mcp, with the www: without it, logging in fails in some clients. Then check that your key reached Gatlas, on the Gatlas page for claude.ai and Claude Desktop, or in the command or configuration for Claude Code and Cursor.
  • The key is refused. A Gatlas key starts with gat_. Check that you pasted all of it. If it still fails, the key may have been revoked; ask the person who sent it for a new one.
  • The setup link has expired. A setup link works for 30 days from when the key was created, and it cannot be renewed. Ask the person who sent it to send you the key itself, or to create a new key for you.
  • An answer is missing a company or a dataset. Your key may not cover it, or the dataset may not be approved yet. Ask the person who gave you the key.