> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aion.to/llms.txt
> Use this file to discover all available pages before exploring further.

# File MCP

> Use optional MCP tools to manage artifacts and prepare authenticated HTTP uploads.

The **Aion Files** capability is `mcp.aion.files`.
It is disabled by default. A workspace administrator enables it through the normal global MCP settings.
The tools then appear through the existing MCP discovery and execution paths.
Each operation still requires the same [File permissions](https://docs.aion.to/docs/resources/file-service.md#ownership-and-permissions).

The File REST API works independently of this MCP setting.
No project MCP node is required for this global capability.

## Tools

| Tool | Purpose |
| - | - |
| `list_files` | List one purpose and authorized owner with paging and filename search |
| `get_file` | Read full current artifact metadata |
| `prepare_file_upload` | Authorize and describe a later HTTP upload |
| `prepare_file_replacement` | Prepare an HTTP replacement with expected-version checks |
| `update_file_metadata` | Edit metadata with the same preconditions as REST |
| `read_file` | Read up to 128 KiB directly, without a grant |
| `create_file_read_grant` | Explicitly create an exact-version bearer link |
| `renew_file_retention` | Extend available content retention |
| `delete_file` | Delete through the normal lifecycle |

Tool arguments use the REST field names and semantics.
For artifact creation and discovery, `purpose` is required: `AgentArtifact` or `OrganizationArtifact`.
User calls specify `organizationId`; agent callbacks can use the verified payer workspace.
Users can select an authorized `agentIdentityId`; callback ownership stays fixed.
`list_files` accepts `pageSize`, `pageToken`, `fileNameRegex`, and `caseSensitive` with the REST bounds.

Credentials and attribution are transport inputs, not tool arguments.
The runtime uses the verified MCP caller, owner scope, and payer context for each invocation.
A tool cannot replace the caller by supplying an identity or token in its arguments.

## Upload through HTTP

MCP prepares the upload. The host sends the bytes through the File REST API.
The host therefore needs an HTTP client, the local bytes, and the original supported credentials.
A generic MCP client does not automatically perform this transfer.

### 1. Prepare the upload

Call `prepare_file_upload` with metadata only. Use your workspace UUID and a new operation UUID;
keep that operation ID when retrying the same upload:

```json theme={null}
{
  "operationId": "00000000-0000-0000-0000-000000000010",
  "organizationId": "00000000-0000-0000-0000-000000000020",
  "purpose": "AgentArtifact",
  "fileName": "report.csv",
  "mediaType": "text/csv",
  "byteSize": 9,
  "metadata": {"description": "Weekly totals", "tags": ["reports"]}
}
```

The optional `metadata` object accepts only `description` and `tags`. Supply `fileName` as a separate tool argument.
You can also supply an authorized `agentIdentityId` and a future `retentionExpiresAt`.
The tool returns a structured descriptor with `method`, `url`, `parameters`, `operationId`, `fileName`,
`mediaType`, `byteSize`, `metadata`, `maximumBytes`, `requiredHeaders`, and `forwardOriginalHeaders`.
For an agent artifact, its parameters include the resolved owner identity.

The descriptor contains no token or signed attribution. It creates no file, reservation, or storage charge.
The HTTP endpoint checks current authentication, attribution, permissions, and version conditions again.

### 2. Send the bytes

Install the [Python SDK](https://docs.aion.to/sdk/python/installation.md) in the host application.
Pass the tool's structured upload descriptor, local bytes, and the same token manager used by the MCP call.
The token manager must expose `async get_token()` and return a current supported bearer token.
Configure `AION_API_HOST` for the same API origin used by MCP.

```python theme={null}
from aion.api.file_service_client import AionFileClient


async def upload_file(descriptor, content, token_manager, runtime_context=None):
    async with AionFileClient(jwt_manager=token_manager) as files:
        return await files.upload_prepared(
            descriptor,
            content,
            runtime_context=runtime_context,
        )
```

For the preparation example above, `content` is `b"total,42\n"` (nine bytes).
For a callback, pass the original runtime context or call inside its active context so the SDK preserves attribution.
If your host holds the original signed carrier directly, pass it as `usage_attribution` to `upload_prepared`.
Ordinary user or Connect calls without callback attribution omit those arguments.
The SDK checks the configured API origin, File route, method, operation ID, and byte count before sending credentials.
It does not follow redirects, fetch arbitrary URLs, or read filesystem paths supplied by a tool.

The host sends optional JSON metadata first and then exactly one file part.
Prepared uploads allow **20 MiB (20,971,520 bytes)** of file content by default.
Use the descriptor's `maximumBytes` for the server's configured limit.
The HTTP request has a separate allowance for metadata and framing; see
[upload limits](https://docs.aion.to/docs/resources/file-service/rest-api.md#upload-limits).
The 128 KiB MCP inline-read limit does not apply to these HTTP uploads.

### 3. Use the receipt

A successful upload returns `id`, `versionId`, and `revision`, as shown in the
[REST upload response](https://docs.aion.to/docs/resources/file-service/rest-api.md#create-an-artifact).
This HTTP receipt confirms the upload completed; preparing a descriptor alone does not.
No separate MCP finalization call is needed. Retry an uncertain upload with the same descriptor and bytes.

### Replace existing content

`prepare_file_replacement` additionally requires `fileId`, `expectedVersionId`, and `expectedRevision`.
It returns instructions for `PUT /files/{fileId}`. Omitted description and tags stay unchanged.
The required `fileName` becomes the saved filename after replacement.
A conflict requires the caller to inspect the current head before preparing a new edit.

## Read content

`read_file` accepts `fileId` and optional `versionId`.
It returns one embedded base64 resource and file identifiers. It does not create a link or require grant permission.
Content requires `FileRead` and owner authorization, as on REST.

The direct-read limit is **128 KiB of decoded content**.
Larger content returns `file_payload_too_large` with authenticated HTTP guidance.
The service does not truncate content or create a grant as a fallback.

The complete encoded request or result must also fit the **384 KiB** File transport budget.
A MetaTools batch can exceed that limit even when its individual reads fit.
Use separate calls for larger reads. A failed aggregate response does not roll back operations that already completed.

## Metadata, grants, and retention

`update_file_metadata` accepts `fileId`, `operationId`, `expectedVersionId`, `expectedRevision`, and `metadata`.
Omitted editor fields stay unchanged; null clears description or tags; filename cannot be cleared.
The result identifies the accepted version and revision. Bytes are shared with the preceding content version.

`create_file_read_grant` is an explicit sharing operation. It requires `FileUpdate`, `fileId`, and `versionId`.
Optional `ttlSeconds` follows the REST lifetime rules. The result contains a bearer URL: anyone with it can read.
Treat that URL as a secret. Read, list, and upload-preparation tools do not create grants.

`renew_file_retention` requires `fileId` and `retentionExpiresAt`.
The field must be present; explicit null requests indefinite retention.
`delete_file` requires `fileId` and a stable `operationId`.

Domain failures return an MCP tool result with `isError: true` and a safe code and message.
Malformed protocol inputs retain MCP protocol errors. Encoded-size rejection uses `file_mcp_message_too_large`.
The [REST reference](https://docs.aion.to/docs/resources/file-service/rest-api.md) defines the shared metadata limits and lifecycle rules.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.