> For the complete documentation index, see [llms.txt](https://docs.carto.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.carto.com/carto-for-agents/connect-your-platform/microsoft-copilot-studio.md).

# Microsoft Copilot Studio

Copilot Studio connects to CARTO as a **tool** on your Copilot agents. A maker can set it up without an admin, and over OAuth the agent gets the full CARTO tool surface. It's one of the quickest hosts to reach the complete product.

## Requirements

* A Microsoft 365 account with a **Copilot Studio** license.
* Your CARTO **MCP Server URL**.
* For the full surface: a CARTO **SPA OAuth Client** (Client ID + Secret). See [Connecting with OAuth](/carto-for-agents/mcp-server/connecting-with-oauth.md#1-create-the-client-in-carto).

{% hint style="info" %}
**Generative orchestration must be ON** for the agent, or the MCP tools never fire.
{% endhint %}

## Option A — OAuth (full tool surface)

1. In CARTO, create a **SPA OAuth Client** (**Developers > Credentials > SPA OAuth Clients**). For **Application Login URI**, a placeholder like `https://global.consent.azure-apim.net/redirect` is fine. Keep the **Client ID** and **Secret**.
2. In Copilot Studio, open your agent, go to **Tools > Add a tool > Add new MCP**.
3. Fill in:
   * **Server URL** — your CARTO MCP Server URL.
   * **Authentication** — **OAuth 2.0**, Configuration type **Manual**.
   * **Authorization URL** — `https://auth.carto.com/authorize`
   * **Token URL** / **Refresh URL** — `https://auth.carto.com/oauth/token`
   * **Scopes** — `openid profile email offline_access read:workflows write:workflows`
   * **Client ID / Secret** — from step 1.
4. Save. Copilot generates a **per-connector redirect URL** (e.g. `https://global.consent.azure-apim.net/redirect/...`). Copy it.
5. Back in CARTO, open the SPA client, turn off **"Use default logout/callback URLs and Origins"**, and add that exact URL to **Allowed Callback URLs**. Save.
6. Create the connection and complete sign-in in the popup.

<figure><img src="/files/Chwj53E7doHr7UgWGSAa" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
Don't use Copilot's **"Dynamic discovery"** option — it relies on dynamic client registration, which CARTO doesn't use. Always choose **Manual**.
{% endhint %}

{% hint style="info" %}
**Two-step connection.** The connection going green in the authoring screen isn't always enough — at chat time, the end user may need to complete a second connect (**Open connection manager > Connect > Submit**), or click **Retry** in the chat. Each user connects individually. This is expected.
{% endhint %}

## Option B — API key (read-and-discovery, \~2 minutes)

For browse-and-query only, skip OAuth:

1. **Tools > Add a tool > Add new MCP**.
2. Server name, description, and **Server URL**.
3. **Authentication: API key** > Type **Header** > Header name **`Authorization`**.
4. Create a connection with the value `Bearer <your CARTO API Access Token>` (include the word `Bearer`).
5. On your first message, complete the connection prompt (**Connect > Submit**, wait for **Connected**).

This gives the [read-and-discovery subset](/carto-for-agents/mcp-server/connecting-with-api-tokens.md#what-a-token-unlocks) — no map or workflow authoring — and its size depends on which data APIs the token carries.

{% hint style="warning" %}
If both an OAuth tool and an API-key tool are enabled, disable one. Otherwise the orchestrator may pick the API-key server and silently give you the smaller read-and-discovery surface.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.carto.com/carto-for-agents/connect-your-platform/microsoft-copilot-studio.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.