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.
The File REST API works independently of this MCP setting.
No project MCP node is required for this global capability.
Tools
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
Callprepare_file_upload with metadata only. Use your workspace UUID and a new operation UUID;
keep that operation ID when retrying the same upload:
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 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 exposeasync get_token() and return a current supported bearer token.
Configure AION_API_HOST for the same API origin used by MCP.
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.
The 128 KiB MCP inline-read limit does not apply to these HTTP uploads.
3. Use the receipt
A successful upload returnsid, versionId, and revision, as shown in the
REST upload response.
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 defines the shared metadata limits and lifecycle rules.