GitHub Copilot

GitHub Copilot can work with CARTO in three complementary ways:

• MCP Server: gives Copilot access to CARTO tools such as data discovery, SQL, Data Observatory, and other MCP capabilities.

• CARTO CLI: provides command-line access to CARTO for scripting, automation, and administration.

• Agent Skills: provides Copilot with reusable instructions and workflows for working with CARTO.

The MCP setup differs depending on whether you're using VS Code or the Copilot coding agent.

Before you start: Copy your MCP Server URL from CARTO Workspace under Workspace > Settings > MCP Server

MCP

In VS Code

VS Code supports remote MCP servers through .vscode/mcp.json. You can create the configuration manually or run MCP: Add Server from the Command Palette.

Add CARTO as a remote HTTP server:

{
  "servers": {
    "carto": {
      "type": "http",
      "url": "https://<region>.api.carto.com/mcp/<account_id>",
      "headers": { "Authorization": "Bearer ${input:carto_token}" }
    }
  }
}

Replace <region> and <account_id> with the values from your CARTO MCP Server URL.

Using an input variable keeps the CARTO API Access Token out of the configuration file. Don't hardcode the token in .vscode/mcp.json.

If CARTO advertises OAuth, an Auth action appears above the server entry. Select Auth to sign in and use the full CARTO tool surface. This requires VS Code 1.101 or later.

If OAuth isn't available, use a CARTO API Access Token instead.

For more information, see VS Code's MCP documentation.

In the Copilot coding agent

The repository-level Copilot coding agent supports remote HTTP MCP servers but does not support OAuth. Use a CARTO API Access Token instead.

Store the token as a repository or organization secret with a COPILOT_MCP_ prefix. For example:

COPILOT_MCP_CARTO_TOKEN

Configure the MCP server using mcpServers:

{
  "mcpServers": {
    "carto": {
      "type": "http",
      "url": "https://<region>.api.carto.com/mcp/<account_id>",
      "headers": { "Authorization": "Bearer $COPILOT_MCP_CARTO_TOKEN" },
      "tools": ["*"]
    }
  }
}

Replace <region> and <account_id> with the values from your CARTO MCP Server URL.

The tools field controls which MCP tools the coding agent can use. Replace "*" with a focused list if you want to expose only specific CARTO tools.

For more information, see GitHub's documentation on extending Copilot coding agent with MCP.

CARTO CLI

Copilot has access to a terminal, so you can use the CARTO CLI alongside MCP for scripting, automation, and administration.

Install the CLI:

npm install -g @carto/carto-cli

Authenticate:

carto auth login

The CLI is useful when the agent needs to perform command-line operations or when you want to automate CARTO tasks outside the MCP tool interface.

Agent Skills

CARTO Agent Skills provide reusable instructions and workflows that help Copilot work with CARTO consistently.

Copilot does not currently provide a native installer for the CARTO Agent Skills catalog. To use the same guidance, add the relevant CARTO skill playbooks to your repository's custom instructions, for example:

.github/copilot-instructions.md

This gives Copilot the CARTO-specific instructions and workflows, while MCP provides access to the underlying CARTO tools.