> 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

[Microsoft Copilot Studio](https://www.microsoft.com/en-us/microsoft-copilot/microsoft-copilot-studio) connects to CARTO as an **MCP tool** for your Copilot agents. A maker can configure the connection directly in Copilot Studio, and OAuth gives the agent access to the **full CARTO tool surface**.

## Requirements

* A Microsoft 365 account with a **Copilot Studio license**.
* Your CARTO **MCP Server URL**.
* For the full tool surface, a CARTO **SPA OAuth Client** with a **Client ID and Secret**. See [Connecting with OAuth](/carto-for-agents/mcp-server/connecting-with-oauth.md#1-create-the-client-in-carto).
* **Generative orchestration** must be enabled for the agent. Otherwise, the MCP tools won't be invoked.

{% hint style="info" %}
**Generative orchestration must be enabled for the agent to use MCP tools.** See Microsoft's [MCP documentation for Copilot Studio](https://learn.microsoft.com/en-us/microsoft-copilot-studio/agent-extend-action-mcp?utm_source=chatgpt.com).
{% endhint %}

## Connecting via OAuth

OAuth provides access to the **full CARTO tool surface**, including map and Workflow authoring.

1. In CARTO, create a **SPA OAuth Client** under **Developers > Credentials > SPA OAuth Clients**.
   * For **Application Login URI**, a placeholder such as `https://global.consent.azure-apim.net/redirect` is sufficient.
   * Keep the **Client ID** and **Client Secret**.
2. In Copilot Studio, open your agent, go to **Tools > Add a tool > Add new MCP**.
3. Configure the MCP connection:
   * **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.

     <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2FmrcHocj9bJvq1sgcWtU4%2Fimage.png?alt=media&amp;token=237d3e9b-f1c4-4aa8-bd26-086e4a302c66" alt=""><figcaption></figcaption></figure>
4. Save the configuration. Copilot Studio generates a **per-connector redirect URL**, for example: (e.g. `https://global.consent.azure-apim.net/redirect/...`). Copy it.
5. Back in CARTO, open the SPA OAuth Client and turn off **Use default logout/callback URLs and Origins**. Add the Copilot-generated URL to **Allowed Callback URLs**, then save the client.
6. In Copilot Studio, create the connection and complete the **CARTO sign-in** in the popup.

{% hint style="warning" %}
Don't use Copilot Studio'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 showing as active in the authoring screen isn't always enough. When the agent is used in chat, the end user may need to complete a second connection through **Open connection manager → Connect → Submit**, or click **Retry** in the chat. Each user connects individually. This is expected.
{% endhint %}

## Read-only alternative

For **browse-and-query use cases**, you can skip OAuth and use a CARTO API Access Token instead.

1. In Copilot Studio, open your agent and go to **Tools > Add a tool > Add new MCP**.
2. Enter the **Server name**, **Description**, and **Server URL**.
3. Under **Authentication**, select **API key**.
   * **Type:** **Header**
   * **Header name:** `Authorization`
4. Create a connection using: `Bearer <your CARTO API Access Token>` Include the `Bearer` prefix.
5. On your first message, complete the connection prompt by selecting **Connect > Submit** and wait for the connection to show as **Connected**.

This provides the [**read-and-discovery subset**](/carto-for-agents/mcp-server/connecting-with-api-tokens.md#what-a-token-unlocks) **of the CARTO tool surface**. It does not enable map or Workflow authoring, and the available tools depend on the data API scopes carried by the CARTO API Access Token

{% hint style="warning" %}
If both an OAuth MCP tool and an API-key MCP tool are enabled, disable one. Otherwise, the orchestrator may select the API-key connection and expose the smaller read-and-discovery tool surface instead of the full OAuth 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.