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, 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, and handoff	No OAuth required. Bucket operations use the `bucket_name` and `bucket_token` returned by `create_bucket`.
Production MCP server	Tenant-owned buckets, adopted agent 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://agents-mcp.ironshard.ai/mcp`
Initial tool	`create_bucket`
MCP auth	None required for bucket creation

Note: technical values on this page may change as the public Agent MCP surface expands.

Public Agent MCP tools

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

Tool	Purpose	Status
`create_bucket`	Creates a sandbox bucket through IronShard's public Agent MCP flow without tenant OAuth. Takes no arguments. Returns `bucket_name` and `bucket_token`.	Available
`get_bucket`	Returns configuration and policy-visible state for one bucket, including creation time, object count, and versioning status.	Available
`list_buckets`	Lists the buckets reachable with the supplied token, with object counts.	Available
`get_bucket_permissions`	Returns the operations the supplied token is permitted to perform on each bucket it can reach.	Available
`get_bucket_usage`	Returns current storage, request, object-count, and egress usage for the bucket.	Planned
`extend_bucket`	Extends the bucket lifetime or operating window if the bucket policy allows it.	Planned
`revoke_bucket`	Revokes the bucket and disables further access to its data and credentials.	Planned
`generate_bucket_handoff`	Generates a human- or super-agent-facing handoff summary with management links and audit evidence.	Planned
`upload_object`	Creates a short-lived presigned `PUT` URL for uploading an object to the bucket.	Available
`download_object`	Creates a short-lived presigned `GET` URL for downloading an object from the bucket.	Available
`list_objects`	Lists objects in the bucket, with an optional prefix filter, recursive or directory-style listing, and pagination.	Available
`delete_object`	Deletes an object from the bucket. Idempotent: deleting a key that is already gone succeeds.	Available
`get_object_metadata`	Returns object metadata, including size, version ID, ETag, content type, tags, and timestamps.	Available
`copy_object`	Copies an object within the bucket.	Planned
`create_snapshot`	Creates a point-in-time snapshot of the bucket or selected object prefix.	Planned
`list_snapshots`	Lists snapshots available in the bucket.	Planned
`get_snapshot`	Returns metadata for a specific snapshot.	Planned
`restore_snapshot`	Restores data from a snapshot into the bucket.	Planned
`delete_snapshot`	Deletes a snapshot if bucket policy allows deletion.	Planned
`create_branch`	Creates a writable branch from the current bucket state, a snapshot, or another branch.	Planned
`list_branches`	Lists branches in the bucket.	Planned
`get_branch`	Returns metadata and status for a specific branch.	Planned
`delete_branch`	Deletes an unneeded branch and its unmerged changes.	Planned
`create_branch_object_upload_url`	Creates a presigned upload URL for writing an object to a specific branch.	Planned
`create_branch_object_download_url`	Creates a presigned download URL for reading an object from a specific branch.	Planned
`list_objects_on_branch`	Lists objects visible on a specific branch.	Planned
`delete_object_on_branch`	Deletes an object on a branch without affecting the main bucket state until merge.	Planned
`get_branch_object_metadata`	Returns metadata for an object as seen on a specific branch.	Planned
`diff_branch`	Computes the difference between a branch and its base or target branch.	Planned
`get_diff`	Returns details for a previously computed diff, including added, modified, deleted, and conflicting objects.	Planned
`merge_branch`	Merges branch changes into the target branch or main bucket state.	Planned
`discard_branch`	Discards branch changes without merging them.	Planned
`get_audit_log`	Returns audit events for bucket operations, including object writes, reads, branch changes, merges, and credential actions.	Planned

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

Create a bucket

The agent starts by calling create_bucket. It takes no arguments.

// tool call
{
  "tool": "create_bucket",
  "input": {}
}

Example response:

{
  "bucket_name": "autonomous-agent-f80549c3-1645-477f-be20-f5a71dd2439e",
  "bucket_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6..."
}

Every later call requires both bucket_name and bucket_token. The bucket_token is not an OAuth token and does not identify a tenant. It is a bucket-scoped credential and cannot be recovered if lost. If S3-compatible access is returned, those credentials are also scoped to the created bucket.

Store objects

Objects move over short-lived presigned URLs. There is no inline object transfer through MCP.

Request a presigned upload URL:

// tool call
{
  "tool": "upload_object",
  "input": {
    "bucket_name": "autonomous-agent-f80549c3-1645-477f-be20-f5a71dd2439e",
    "bucket_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6...",
    "object_key": "reports/final.pdf"
  }
}

Example response:

{
  "url": "https://s3.ironshard.ai/autonomous-agent-f80549c3-1645-477f-be20-f5a71dd2439e/reports/final.pdf?X-Amz-Algorithm=...",
  "http_method": "PUT"
}

Send the object bytes as the body of an HTTP PUT to that URL. The URL carries its own authorization, so no additional headers are required, and there is no separate completion step. Reading an object works the same way through download_object, which returns an equivalent GET URL whose response body contains the bytes.

Presigned URLs are short-lived bearer capabilities. Treat them as secrets and request a fresh one rather than storing them.

Confirm a write with get_object_metadata:

{
  "object_key": "reports/final.pdf",
  "size_bytes": 18,
  "last_modified": "2026-08-26T08:10:51",
  "etag": "7c6da1838ff3a268a32c9e1c26230fc3",
  "version_id": "46",
  "content_type": "application/pdf",
  "bucket_name": "autonomous-agent-f80549c3-1645-477f-be20-f5a71dd2439e",
  "metadata": {},
  "tags": {}
}

Use branches

This workflow depends on tools marked Planned and is not yet available on the public Agent MCP server.

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 request a presigned upload URL scoped to the branch:

// tool call
{
  "tool": "create_branch_object_upload_url",
  "input": {
    "bucket_id": "agb_9f3a21c0",
    "bucket_token": "ist_bucket_...",
    "branch": "analysis-draft",
    "object_key": "notes/summary.json"
  }
}

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"
  }
}

Handoff and adoption

This workflow depends on tools marked Planned and is not yet available on the public Agent MCP server.

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;
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 remains 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 set by the active bucket policy and are subject to change.

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.
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.