ServicesAboutNotesContact Get in touch →
EN FR
Note

GCP Application Default Credentials

The difference between gcloud auth login and Application Default Credentials — why they exist, how they work, and why ADC is what MCP servers and SDKs actually use.

Planted
gcpbigquerydata engineering

Application Default Credentials (ADC) is the most common source of authentication confusion in the GCP ecosystem. The confusion comes from having two separate authentication mechanisms that look similar but serve different purposes — and most people only set up one of them.

Two Authentication Mechanisms

gcloud auth login authenticates the gcloud CLI. When you run gcloud projects list or bq query --sql "SELECT 1", this is the credential being used. It’s your identity for Google Cloud command-line tools.

gcloud auth application-default login sets up Application Default Credentials. This is a separate credential used by applications, SDKs, and libraries that call Google Cloud APIs programmatically. When a Python script uses google.cloud.bigquery.Client(), or when the MCP Toolbox connects to BigQuery, they use ADC — not your gcloud CLI credentials.

You need both. Having one does not imply the other.

Terminal window
# Authenticates gcloud CLI commands
gcloud auth login


# Sets up ADC for applications and SDKs
gcloud auth application-default login

The second command opens a browser for OAuth consent. Once you approve, credentials are stored at ~/.config/gcloud/application_default_credentials.json. Any application looking for ADC checks that file.

Why Two Mechanisms Exist

The distinction exists because gcloud CLI commands and application code have different authentication needs.

The gcloud CLI is an interactive tool. It authenticates as you — your Google identity, your permissions, your audit trail. The credential is scoped to the CLI and doesn’t leak into applications running on your machine.

Applications and SDKs need credentials they can use programmatically, without interactive prompts. ADC provides a standardized way for any Google Cloud client library to find credentials, regardless of where the code runs. The same application code works locally (using your ADC from gcloud auth application-default login), in Cloud Run (using the service’s attached service account), in GKE (using Workload Identity), or in a VM (using the compute instance’s service account).

This portability is the whole point. You write your code once, and ADC resolves the right credential for the environment.

The Credential Resolution Chain

When an application uses ADC, Google’s client libraries check for credentials in this order:

  1. GOOGLE_APPLICATION_CREDENTIALS environment variable — if set, use the service account key file at this path
  2. User credentials from gcloud auth application-default login — the file at ~/.config/gcloud/application_default_credentials.json
  3. Attached service account — in Cloud Run, GKE, Compute Engine, the instance’s metadata service provides credentials automatically

For local development, most people hit #2. For production, you usually want #1 (explicit service account) or #3 (attached service account).

The MCP Authentication Problem

This dual-mechanism setup is specifically why authentication for MCP servers trips people up. The typical failure mode:

  1. Developer runs gcloud auth login (already done, since they use gcloud regularly)
  2. Developer installs the MCP Toolbox and runs it
  3. The Toolbox tries to use ADC
  4. ADC has never been set up
  5. The Toolbox silently fails or returns empty results
  6. Developer assumes the MCP server is broken

The fix is always the same: gcloud auth application-default login, then restart the MCP client.

The Remote MCP Server sidesteps this problem in Claude Desktop by handling OAuth internally. But when using the Toolbox, ADC is the authentication path.

Service Accounts for Production

For production use, don’t rely on personal ADC. Create a dedicated service account with minimal permissions and set GOOGLE_APPLICATION_CREDENTIALS:

Terminal window
# Create the service account
gcloud iam service-accounts create bigquery-mcp \
  --display-name="BigQuery MCP Service Account"


# Grant minimum required roles
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:bigquery-mcp@PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/bigquery.user"


gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:bigquery-mcp@PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/bigquery.dataViewer"


# Create and download key file
gcloud iam service-accounts keys create bigquery-mcp-key.json \
  --iam-account=bigquery-mcp@PROJECT_ID.iam.gserviceaccount.com

Then point ADC to the key:

Terminal window
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/bigquery-mcp-key.json"

Rotate the key periodically. The BigQuery IAM Patterns note covers the broader service account strategy — including why Workload Identity Federation is preferable to key files when running in GCP environments.

The Restart Requirement

One critical behavior: most applications (including MCP servers) read ADC once at startup. If you update your credentials while the application is running, it won’t pick up the change. You must restart the application after changing credentials.

With Claude Code, this sometimes means restarting twice: once for the MCP server configuration, and once for the new credentials to take effect.