GCS Connector

Availability

The GCS connector is available in the current community runtime. Evaluation and Enterprise add broader managed-connector workflows, but GCS itself is part of the public MCP connector surface.

The GCS connector enables AxonFlow agents to interact with Google Cloud Storage for storing and retrieving objects.

It is a strong fit for document pipelines, governed retrieval workflows, analytics exports, and internal assistants deployed in Google Cloud environments.

Overview

Property	Value
Type	`gcs`
Edition	Community
Auth Methods	Service Account Key, Workload Identity, Application Default Credentials
Capabilities	query, execute, presign, streaming

Use Cases

Store documents for RAG pipelines in Google Cloud environments
Archive agent outputs and generated reports
Access data from BigQuery export jobs
Integrate with GCP-native applications
Support governed enterprise AI document and retrieval workflows on Google Cloud

Configuration

Environment Variables

# Required
MCP_gcs_storage_PROJECT_ID="my-gcp-project"
MCP_gcs_storage_DEFAULT_BUCKET="my-bucket"

# Authentication (choose one method)

# Option 1: Service Account Key File
MCP_gcs_storage_CREDENTIALS_FILE="/path/to/service-account.json"

# Option 2: Service Account Key JSON (inline)
MCP_gcs_storage_CREDENTIALS_JSON='{"type":"service_account","project_id":"my-project",...}'

# Option 3: Workload Identity (recommended for GKE)
# No credentials needed - uses workload identity automatically

# Option 4: Application Default Credentials
# Uses GOOGLE_APPLICATION_CREDENTIALS env var or gcloud auth

# Optional
MCP_gcs_storage_ENDPOINT="https://storage.googleapis.com"  # Custom endpoint for emulator
MCP_gcs_storage_TIMEOUT="30s"

Connector Config (Customer Portal)

{
  "name": "gcs-documents",
  "type": "gcs",
  "options": {
    "project_id": "my-gcp-project",
    "default_bucket": "documents-bucket"
  },
  "credentials": {
    "credentials_file": "/secrets/gcs/service-account.json"
  }
}

Operations

Query Operations

List Objects

curl -X POST https://your-axonflow.example.com/mcp/resources/query \
  -H "Content-Type: application/json" \
  -d '{
    "connector": "gcs-documents",
    "statement": "list_objects",
    "parameters": {
      "bucket": "my-bucket",
      "prefix": "documents/",
      "max_results": 100
    }
  }'

Response:

{
  "rows": [
    {
      "name": "documents/report.pdf",
      "size": 102400,
      "updated": "2025-12-07T10:30:00Z",
      "content_type": "application/pdf",
      "generation": "1733570400000000"
    }
  ],
  "metadata": {
    "bucket": "my-bucket"
  }
}

Get Object

curl -X POST https://your-axonflow.example.com/mcp/resources/query \
  -d '{
    "connector": "gcs-documents",
    "statement": "get_object",
    "parameters": {
      "bucket": "my-bucket",
      "key": "documents/report.pdf"
    }
  }'

Get Object Metadata

curl -X POST https://your-axonflow.example.com/mcp/resources/query \
  -d '{
    "connector": "gcs-documents",
    "statement": "get_metadata",
    "parameters": {
      "key": "documents/report.pdf"
    }
  }'

Generate Signed URL

curl -X POST https://your-axonflow.example.com/mcp/resources/query \
  -d '{
    "connector": "gcs-documents",
    "statement": "signed_url",
    "parameters": {
      "key": "documents/report.pdf",
      "method": "GET",
      "expires_in": 3600
    }
  }'

List Buckets

curl -X POST https://your-axonflow.example.com/mcp/resources/query \
  -d '{
    "connector": "gcs-documents",
    "statement": "list_buckets",
    "parameters": {
      "prefix": "prod-"
    }
  }'

Execute Operations

Put Object

curl -X POST https://your-axonflow.example.com/mcp/tools/execute \
  -d '{
    "connector": "gcs-documents",
    "action": "put_object",
    "parameters": {
      "bucket": "my-bucket",
      "key": "uploads/new-file.txt",
      "body": "File content here",
      "content_type": "text/plain"
    }
  }'

Delete Object

curl -X POST https://your-axonflow.example.com/mcp/tools/execute \
  -d '{
    "connector": "gcs-documents",
    "action": "delete_object",
    "parameters": {
      "key": "uploads/old-file.txt"
    }
  }'

Copy Object

curl -X POST https://your-axonflow.example.com/mcp/tools/execute \
  -d '{
    "connector": "gcs-documents",
    "action": "copy_object",
    "parameters": {
      "source_bucket": "source-bucket",
      "source_key": "original.pdf",
      "dest_bucket": "dest-bucket",
      "dest_key": "copy.pdf"
    }
  }'

Create Bucket

curl -X POST https://your-axonflow.example.com/mcp/tools/execute \
  -d '{
    "connector": "gcs-documents",
    "action": "create_bucket",
    "parameters": {
      "bucket": "new-bucket-name",
      "location": "us-central1",
      "storage_class": "STANDARD"
    }
  }'

Delete Bucket

curl -X POST https://your-axonflow.example.com/mcp/tools/execute \
  -d '{
    "connector": "gcs-documents",
    "action": "delete_bucket",
    "parameters": {
      "bucket": "old-bucket"
    }
  }'

Authentication Methods

Workload Identity (Recommended for GKE)

For GKE deployments, use Workload Identity to avoid managing keys:

Enable Workload Identity on GKE cluster
Create a GCP service account with Storage permissions
Bind Kubernetes service account to GCP service account

# Bind KSA to GSA
gcloud iam service-accounts add-iam-policy-binding \
  [email protected] \
  --role roles/iam.workloadIdentityUser \
  --member "serviceAccount:my-project.svc.id.goog[axonflow/axonflow-agent]"

No credentials environment variables needed - the connector auto-detects Workload Identity.

Service Account Key

For non-GKE deployments:

MCP_gcs_storage_CREDENTIALS_FILE="/secrets/gcs/service-account.json"

Required IAM Roles:

roles/storage.objectViewer for read-only
roles/storage.objectAdmin for read/write
roles/storage.admin for bucket management

IAM Permissions

Required Roles by Operation

The connector requires specific GCS IAM permissions depending on the operations you use:

Operation	Minimum IAM Role
`list_objects`, `get_object`, `get_metadata`	`roles/storage.objectViewer`
`put_object`, `copy_object`, `delete_object`	`roles/storage.objectAdmin`
`list_buckets`, `create_bucket`, `delete_bucket`	`roles/storage.admin`
`signed_url`	`roles/storage.objectViewer` + `roles/iam.serviceAccountTokenCreator`

Bucket-Level IAM

For tighter security, grant permissions at the bucket level instead of the project level:

# Grant read-only access to a specific bucket
gcloud storage buckets add-iam-policy-binding gs://my-bucket \
  --member="serviceAccount:[email protected]" \
  --role="roles/storage.objectViewer"

# Grant read-write access to a specific bucket
gcloud storage buckets add-iam-policy-binding gs://my-bucket \
  --member="serviceAccount:[email protected]" \
  --role="roles/storage.objectAdmin"

Bucket-level IAM bindings take precedence over project-level deny policies, so you can use a combination of project-level deny and bucket-level allow for fine-grained access control.

Composite Objects

For very large files (multi-GB), GCS supports composite objects that combine up to 32 component objects into a single object. The connector handles this automatically for uploads exceeding the multipart threshold. Note that composite objects have a maximum of 32 components; composing objects that are themselves composites counts toward this limit.

Best Practices

Security

Use Workload Identity in GKE (no keys to manage)
Scope IAM permissions to specific buckets (see IAM Permissions)
Enable Object Versioning for critical data
Use signed URLs for temporary access

Performance

Use regional buckets close to your compute
Enable parallel uploads for large files
Use composite objects for very large files (see Composite Objects)

Local Development with Emulator

For local development, use the GCS emulator:

# Start fake-gcs-server
docker run -d -p 4443:4443 fsouza/fake-gcs-server

# Configure connector
MCP_gcs_local_ENDPOINT="http://localhost:4443/storage/v1/"
MCP_gcs_local_PROJECT_ID="test-project"
MCP_gcs_local_DEFAULT_BUCKET="test-bucket"
# No credentials needed for emulator

Troubleshooting

Permission Denied

Verify service account has required IAM roles
Check bucket-level IAM bindings
Ensure Workload Identity is configured correctly

Bucket Not Found

Verify bucket name is correct (globally unique)
Check project ID matches bucket's project
Ensure service account has access to the project

Signed URL Invalid

Check service account has iam.serviceAccounts.signBlob permission
Verify system clock is synchronized
Ensure credentials file is accessible

Connection to Emulator Failed

Verify emulator is running on correct port
Check endpoint URL includes /storage/v1/ path
Ensure no HTTPS certificate verification for local endpoint

Overview​

Use Cases​

Configuration​

Environment Variables​

Connector Config (Customer Portal)​

Operations​

Query Operations​

List Objects​

Get Object​

Get Object Metadata​

Generate Signed URL​

List Buckets​

Execute Operations​

Put Object​

Delete Object​

Copy Object​

Create Bucket​

Delete Bucket​

Authentication Methods​

Workload Identity (Recommended for GKE)​

Service Account Key​

IAM Permissions​

Required Roles by Operation​

Bucket-Level IAM​

Composite Objects​

Best Practices​

Security​

Performance​

Local Development with Emulator​

Troubleshooting​

Permission Denied​

Bucket Not Found​

Signed URL Invalid​

Connection to Emulator Failed​

Related​