GCS Connector

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

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

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.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.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.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.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.com/mcp/resources/query \
  -d '{
    "connector": "gcs-documents",
    "statement": "list_buckets",
    "parameters": {
      "prefix": "prod-"
    }
  }'

Execute Operations

Put Object

curl -X POST https://your-axonflow.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.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.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.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.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:

1. Enable Workload Identity on GKE cluster
2. Create a GCP service account with Storage permissions
3. 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

Best Practices

Security

1. Use Workload Identity in GKE (no keys to manage)
2. Scope IAM permissions to specific buckets
3. Enable Object Versioning for critical data
4. Use signed URLs for temporary access

Performance

1. Use regional buckets close to your compute
2. Enable parallel uploads for large files
3. Use composite objects for very large files

Example IAM Binding

# Grant Storage Object Admin on specific bucket
gcloud storage buckets add-iam-policy-binding gs://my-bucket \
  --member="serviceAccount:[email protected]" \
  --role="roles/storage.objectAdmin"

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

Related

• S3 Connector
• Azure Blob Connector
• MCP Overview