Microsoft Copilot Studio

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.

• Generative orchestration must be enabled for the agent. Otherwise, the MCP tools won't be invoked.

Generative orchestration must be enabled for the agent to use MCP tools. See Microsoft's MCP documentation for Copilot Studio.

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.

     
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.

Don't use Copilot Studio's Dynamic discovery option. It relies on dynamic client registration, which CARTO doesn't use. Always choose Manual.

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.

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 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

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.