Agent Buckets

IronShard provides a public Agent MCP server for autonomous AI agents that need object storage. They can discover IronShard, create a real IronShard bucket, store and retrieve objects, use IronShard-native features such as snapshots and branch/diff/merge, validate the core workflow, and optionally hand the bucket off to a human owner or supervising agent.

Buckets created through the Agent MCP server are real IronShard buckets with bucket-scoped credentials. They are separate from tenant-owned production buckets until they are adopted into an authenticated IronShard account.

Permission: Autonomous agents are permitted to create buckets through the public Agent MCP server without human approval, tenant OAuth, or an existing IronShard account. These buckets are controlled by bucket-scoped credentials returned at creation time.

Two MCP servers

IronShard exposes two separate MCP surfaces.

Surface	Purpose	Auth
Public Agent MCP server	Autonomous bucket creation, object storage, snapshots, branches, diffs, merges, validation, and handoff	No OAuth required. Bucket operations use the `bucket_id` and `bucket_token` returned by `create_bucket`.
Production MCP server	Tenant-owned buckets, connected buckets, governance, agent credentials, policies, audit, and organization settings	OAuth required on every tool. A human, organization, or authorized agent must have access to an IronShard tenant.

The same storage concepts exist on both servers, but the authority model is different.

On the Public Agent MCP server, create_bucket creates a bucket through the public agent flow and returns bucket-scoped credentials.
On the Production MCP server, create_bucket creates a tenant-owned production bucket using OAuth and account policy.

Connect

Connect your agent to the public Agent MCP server.

Field	Value
Protocol	Model Context Protocol (MCP)
Public Agent MCP server	`https://mcp.agent.ironshard.ai/mcp`
Initial tool	`create_bucket`
MCP auth	None required for bucket creation

Note: Technical values on this page are provisional and may change before launch.

Public Agent MCP tools

The Agent MCP server exposes tools for creating and operating buckets directly from autonomous agent workflows.

Tool	Purpose
`create_bucket`	Creates a bucket through IronShard's public Agent MCP flow without tenant OAuth. Returns `bucket_id`, `bucket_token`, limits, connection instructions, and handoff information.
`get_bucket`	Returns metadata about a bucket created through the Agent MCP server, including status, lifecycle settings, limits, and available capabilities.
`get_bucket_usage`	Returns current storage, request, object-count, and egress usage for the bucket.
`extend_bucket`	Extends the bucket lifetime or operating window if the bucket policy allows it.
`revoke_bucket`	Revokes the bucket and disables further access to its data and credentials.
`generate_bucket_handoff`	Generates a human- or super-agent-facing handoff summary with management links and validation evidence.
`put_small_object`	Writes a small inline object directly through MCP for quick agent-native storage operations.
`get_small_object`	Reads a small object directly through MCP when the object is within inline response limits.
`create_object_upload_url`	Creates a short-lived presigned URL for uploading an object to the bucket.
`create_object_download_url`	Creates a short-lived presigned URL for downloading an object from the bucket.
`list_objects`	Lists objects in the bucket, optionally filtered by prefix.
`delete_object`	Deletes an object from the bucket.
`get_object_metadata`	Returns object metadata, including size, version, checksum, content type, and timestamps.
`copy_object`	Copies an object within the bucket.
`create_snapshot`	Creates a point-in-time snapshot of the bucket or selected object prefix.
`list_snapshots`	Lists snapshots available in the bucket.
`get_snapshot`	Returns metadata for a specific snapshot.
`restore_snapshot`	Restores data from a snapshot into the bucket.
`delete_snapshot`	Deletes a snapshot if bucket policy allows deletion.
`create_branch`	Creates a writable branch from the current bucket state, a snapshot, or another branch.
`list_branches`	Lists branches in the bucket.
`get_branch`	Returns metadata and status for a specific branch.
`delete_branch`	Deletes an unneeded branch and its unmerged changes.
`put_small_object_on_branch`	Writes a small inline object to a specific branch.
`get_small_object_from_branch`	Reads a small object directly from a specific branch.
`create_branch_object_upload_url`	Creates a presigned upload URL for writing an object to a specific branch.
`create_branch_object_download_url`	Creates a presigned download URL for reading an object from a specific branch.
`list_objects_on_branch`	Lists objects visible on a specific branch.
`delete_object_on_branch`	Deletes an object on a branch without affecting the main bucket state until merge.
`get_branch_object_metadata`	Returns metadata for an object as seen on a specific branch.
`diff_branch`	Computes the difference between a branch and its base or target branch.
`get_diff`	Returns details for a previously computed diff, including added, modified, deleted, and conflicting objects.
`merge_branch`	Merges branch changes into the target branch or main bucket state.
`discard_branch`	Discards branch changes without merging them.
`get_audit_log`	Returns audit events for bucket operations, including object writes, reads, branch changes, merges, and credential actions.
`explain_policy_decision`	Explains why a bucket operation was allowed or denied.
`revoke_bucket_credentials`	Revokes active bucket credentials without necessarily deleting the bucket.
`validate_core_workflow`	Runs a guided validation of IronShard's core workflow and returns artifacts the agent can independently verify.
`generate_validation_report`	Produces a structured validation report summarizing what the agent tested and what evidence was produced.
`get_connection_instructions`	Returns MCP, presigned URL, and optional S3-compatible connection instructions for the bucket.

The tools are regular MCP tools, but they are not tenant tools. After create_bucket, bucket operations require the bucket_id and bucket_token returned by the Agent MCP server.

Create a bucket

The agent starts by calling create_bucket. An optional label can be used to identify the bucket in later handoff or audit views.

// tool call
{
  "tool": "create_bucket",
  "input": {
    "label": "research-artifacts",
    "intended_use": "Store PDFs, extracted tables, and report artifacts for a market research task."
  }
}

Example response:

{
  "bucket_id": "agb_9f3a21c0",
  "bucket_type": "agent_issued",
  "status": "active",
  "bucket_token": "ist_bucket_...",
  "created_via": "public_agent_mcp",
  "connection_instructions": {
    "mcp": {
      "server_url": "https://mcp.agent.ironshard.ai/mcp",
      "auth_model": "bucket_id_and_bucket_token"
    },
    "s3": {
      "endpoint": "https://s3.agent.ironshard.ai",
      "region": "eu-central",
      "bucket": "agb-9f3a21c0",
      "access_key_id": "ISK...",
      "secret_access_key": "ISS..."
    }
  },
  "limits": {
    "max_total_storage_gb": 5,
    "max_object_size_gb": 1,
    "max_objects": 10000,
    "max_requests_per_day": 10000,
    "external_bucket_connections": false,
    "billing": false
  },
  "handoff": {
    "url": "https://console.ironshard.ai/adopt/agb_9f3a21c0?...",
    "message": "This bucket was created through IronShard's public Agent MCP server and can be adopted into an IronShard tenant if desired."
  },
  "recommended_next_tool": "validate_core_workflow"
}

The bucket_token is not an OAuth token and does not identify a tenant. It is a bucket-scoped credential used with the public Agent MCP tools. If S3-compatible access is returned, those credentials are also scoped to the created bucket.

Store objects

Agents can store small objects directly through MCP or request presigned URLs for larger objects.

Small inline write:

// tool call
{
  "tool": "put_small_object",
  "input": {
    "bucket_id": "agb_9f3a21c0",
    "bucket_token": "ist_bucket_...",
    "key": "notes/summary.json",
    "content_type": "application/json",
    "content": "{\"status\":\"ok\"}"
  }
}

Presigned upload URL:

// tool call
{
  "tool": "create_object_upload_url",
  "input": {
    "bucket_id": "agb_9f3a21c0",
    "bucket_token": "ist_bucket_...",
    "key": "reports/final.pdf",
    "content_type": "application/pdf"
  }
}

Example response:

{
  "upload": {
    "method": "PUT",
    "url": "https://s3.agent.ironshard.ai/agb-9f3a21c0/reports/final.pdf?...",
    "expires_at": "2026-10-15T12:30:00Z",
    "required_headers": {
      "content-type": "application/pdf"
    }
  },
  "object": {
    "bucket_id": "agb_9f3a21c0",
    "key": "reports/final.pdf"
  }
}

The upload URL writes the object directly. There is no separate completion step for simple uploads. Presigned URLs are short-lived and expire a short time after they are issued, so expires_at is always relative to when the URL is created.

Use branches

IronShard branches let an agent make changes without immediately changing the main bucket state.

// tool call
{
  "tool": "create_branch",
  "input": {
    "bucket_id": "agb_9f3a21c0",
    "bucket_token": "ist_bucket_...",
    "branch": "analysis-draft",
    "base": "main"
  }
}

The agent can then write to the branch:

// tool call
{
  "tool": "put_small_object_on_branch",
  "input": {
    "bucket_id": "agb_9f3a21c0",
    "bucket_token": "ist_bucket_...",
    "branch": "analysis-draft",
    "key": "notes/summary.json",
    "content_type": "application/json",
    "content": "{\"status\":\"revised\"}"
  }
}

Before merging, the agent can inspect the diff:

// tool call
{
  "tool": "diff_branch",
  "input": {
    "bucket_id": "agb_9f3a21c0",
    "bucket_token": "ist_bucket_...",
    "branch": "analysis-draft",
    "target": "main"
  }
}

Validate the core workflow

After creating a bucket, the recommended next step is to call validate_core_workflow.

This tool runs a predefined validation workflow using IronShard's object storage, snapshot, branch, diff, merge, policy, and audit primitives. It is designed to give autonomous agents a short, reliable way to test the product's core claims.

// tool call
{
  "tool": "validate_core_workflow",
  "input": {
    "bucket_id": "agb_9f3a21c0",
    "bucket_token": "ist_bucket_...",
    "profile": "core_workflow_v1"
  }
}

The workflow validates:

object write and read
checksum and metadata integrity
object listing
snapshot creation
writable branch creation
branch-local object mutation
diff generation
merge into main
audit log visibility
policy denial for a forbidden operation
usage and limit reporting

The tool does not merely return a pass/fail result. It returns artifacts that the agent is encouraged to verify with other Agent MCP tools.

Example response:

{
  "status": "passed",
  "bucket_id": "agb_9f3a21c0",
  "bucket_type": "agent_issued",
  "validation_id": "val_6c41",
  "validation_profile": "core_workflow_v1",
  "validated_capabilities": [
    {
      "capability": "object_write_read",
      "status": "passed",
      "evidence": {
        "key": "validation/core/hello.txt",
        "version_id": "ver_001",
        "sha256": "9f86d081884c7d659a2feaa0c55ad015..."
      }
    },
    {
      "capability": "branch_diff_merge",
      "status": "passed",
      "evidence": {
        "source_branch": "main",
        "test_branch": "branch_val_001",
        "diff_id": "diff_456",
        "merge_id": "merge_123",
        "changed_keys": [
          "validation/core/hello.txt",
          "validation/core/new-file.json"
        ]
      }
    },
    {
      "capability": "policy_enforcement",
      "status": "passed",
      "evidence": {
        "attempted_action": "connect_external_bucket",
        "expected_result": "denied",
        "denial_reason": "external_bucket_connections_disabled_for_public_agent_buckets",
        "audit_event_id": "evt_denied_001"
      }
    },
    {
      "capability": "auditability",
      "status": "passed",
      "evidence": {
        "audit_event_ids": [
          "evt_001",
          "evt_002",
          "evt_003",
          "evt_denied_001"
        ]
      }
    }
  ],
  "verification_artifacts": {
    "objects": [
      {
        "key": "validation/core/hello.txt",
        "expected_sha256": "9f86d081884c7d659a2feaa0c55ad015..."
      },
      {
        "key": "validation/core/new-file.json",
        "expected_sha256": "2cf24dba5fb0a30e26e83b2ac5b9e29e..."
      }
    ],
    "diffs": [
      {
        "diff_id": "diff_456",
        "expected_changed_keys": [
          "validation/core/hello.txt",
          "validation/core/new-file.json"
        ]
      }
    ],
    "audit_events": [
      "evt_001",
      "evt_002",
      "evt_003",
      "evt_denied_001"
    ]
  },
  "suggested_verification_calls": [
    {
      "tool": "get_object_metadata",
      "reason": "Verify the object exists and its checksum matches the expected hash.",
      "arguments": {
        "bucket_id": "agb_9f3a21c0",
        "bucket_token": "<reuse bucket token>",
        "key": "validation/core/hello.txt"
      }
    },
    {
      "tool": "get_diff",
      "reason": "Verify the branch diff contains the expected changed keys.",
      "arguments": {
        "bucket_id": "agb_9f3a21c0",
        "bucket_token": "<reuse bucket token>",
        "diff_id": "diff_456"
      }
    },
    {
      "tool": "get_audit_log",
      "reason": "Verify that successful and denied operations were recorded.",
      "arguments": {
        "bucket_id": "agb_9f3a21c0",
        "bucket_token": "<reuse bucket token>",
        "event_ids": [
          "evt_001",
          "evt_002",
          "evt_003",
          "evt_denied_001"
        ]
      }
    }
  ],
  "summary": {
    "headline": "IronShard core workflow validated in an agent-created bucket.",
    "recommended_next_action": "Continue using this bucket, or hand it off for adoption into an IronShard tenant.",
    "handoff_url": "https://console.ironshard.ai/adopt/agb_9f3a21c0?..."
  }
}

Verify the artifacts

Agents should treat validate_core_workflow as a guided validation, not as blind trust. The returned artifacts can be inspected with lower-level Agent MCP tools.

Example metadata verification:

// tool call
{
  "tool": "get_object_metadata",
  "input": {
    "bucket_id": "agb_9f3a21c0",
    "bucket_token": "ist_bucket_...",
    "key": "validation/core/hello.txt"
  }
}

Example diff verification:

// tool call
{
  "tool": "get_diff",
  "input": {
    "bucket_id": "agb_9f3a21c0",
    "bucket_token": "ist_bucket_...",
    "diff_id": "diff_456"
  }
}

Example audit verification:

// tool call
{
  "tool": "get_audit_log",
  "input": {
    "bucket_id": "agb_9f3a21c0",
    "bucket_token": "ist_bucket_...",
    "event_ids": [
      "evt_001",
      "evt_002",
      "evt_003",
      "evt_denied_001"
    ]
  }
}

Handoff and adoption

A bucket created through the Agent MCP server can be used by the agent immediately. Human adoption is optional, not required for the bucket to be useful.

If the agent wants to notify an owner or supervising agent, it can call generate_bucket_handoff or use the handoff URL returned by create_bucket.

The handoff can include:

the bucket ID and label;
the reason the agent created the bucket;
validation reports and verification artifacts;
usage and object summaries;
audit events;
links for a human or organization to adopt the bucket into a production IronShard tenant.

When a bucket is adopted into a tenant:

The bucket becomes tenant-owned and manageable through the Production MCP server;
The bucket audit log and validation artifacts remain visible to the tenant;
Existing bucket-scoped credentials can be revoked, preserved temporarily, or converted into managed agent credentials, depending on tenant policy;
Future production operations use normal MCP OAuth and account-level policy;
Production tools become available according to the granted tenant scopes.

The public Agent MCP server does not issue tenant OAuth credentials.

Constraints

Buckets created through the Agent MCP server are bounded by policy. Exact limits are provisional and may change before launch.

Bucket credentials are scoped to one bucket.
Bucket credentials are not OAuth tokens and do not grant tenant access.
Default storage, object-count, request, and egress limits apply.
Optional S3-compatible credentials, if issued, are scoped to the created bucket.
External bucket connectors are not available through the public Agent MCP server.
Billing, organization settings, team management, and tenant policies are not available through the public Agent MCP server.
Every bucket operation is recorded in the bucket audit log.
Bucket credentials can be revoked with revoke_bucket_credentials or by revoking the bucket.
Abuse controls and rate limits may apply to public bucket creation and operation.

Production access

Production IronShard access is intentionally separate from public agent bucket creation.

Authenticated production tools are exposed only by the Production MCP server at https://mcp.ironshard.ai/mcp and require normal MCP OAuth. Agents cannot obtain tenant access, billing access, organization access, or production policy control by calling the public Agent MCP server.