Lets an AI client securely upload, share, and manage expiring files and artifacts using encrypted links and automated JSON responses.
Also known as aispace-sh/aispace-client, aispace-client, @aispace-sh/cli
- Stars
- 13
- Tools
- —
- Downloads, 30 days
- 175
- Latest version
- 0.4.1
- Last commit
- Nov 15, 2026
- License
- MIT
What is aispace MCP?
aispace lets an AI client securely upload, share, and manage expiring files and artifacts using encrypted links and automated JSON responses.
Summary generated from the project's README
About aispace MCP server
Developers and AI agents can use aispace to securely upload, share, and manage temporary files and artifacts. It provides a way to handle outputs that are too large or structured for standard chat interfaces by using expiring links and automated JSON responses. The system is designed for automation, offering a scriptable CLI with stable exit codes and predictable machine-readable output via the --json flag.
Users can manage file visibility through private, account-wide, or public link modes. For enhanced security, the server supports local encryption using the age X25519 flow, ensuring filenames and content remain private. The MCP implementation exposes ten typed tools over local stdio, allowing clients like Claude to perform actions such as aispace_create_link, aispace_revoke_link, and aispace_delete_file. Setup requires an API key from the aispace dashboard, which can be provided via the AISPACE_KEY environment variable.
What you can do with it
- 1Automated artifact handoffAn AI agent can upload a generated report and provide a machine-readable link for the user.
- 2Local content encryptionDevelopers can encrypt files locally before they are uploaded so that the master key never reaches the server.
- 3Managing remote filesAn AI client can use MCP tools to revoke access to a link or delete a file from the server.
Written from the project's README. Every use case is checked against a quote from it.
How to install aispace MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall aispace MCP in Claude Code
$ claude mcp add --env 'AISPACE_KEY=<YOUR_AISPACE_KEY>' aispace-client -- npx -y @aispace-sh/cliInstall aispace MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"aispace-client": {
"command": "npx",
"args": [
"-y",
"@aispace-sh/cli"
],
"env": {
"AISPACE_KEY": "<YOUR_AISPACE_KEY>"
}
}
}
}Install aispace MCP in VS Code
.vscode/mcp.json
{
"servers": {
"aispace-client": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@aispace-sh/cli"
],
"env": {
"AISPACE_KEY": "<YOUR_AISPACE_KEY>"
}
}
}
}Install aispace MCP in VS Code CLI
$ code --add-mcp '{"name":"aispace-client","type":"stdio","command":"npx","args":["-y","@aispace-sh/cli"],"env":{"AISPACE_KEY":"<YOUR_AISPACE_KEY>"}}'Install aispace MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"aispace-client": {
"command": "npx",
"args": [
"-y",
"@aispace-sh/cli"
],
"env": {
"AISPACE_KEY": "<YOUR_AISPACE_KEY>"
}
}
}
}Install aispace MCP in Codex
$ codex mcp add aispace-client --env 'AISPACE_KEY=<YOUR_AISPACE_KEY>' -- npx -y @aispace-sh/cliInstall aispace MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.aispace-client] command = "npx" args = ["-y", "@aispace-sh/cli"] [mcp_servers.aispace-client.env] AISPACE_KEY = "<YOUR_AISPACE_KEY>"
Install aispace MCP in Gemini CLI
$ gemini mcp add -s user -e 'AISPACE_KEY=<YOUR_AISPACE_KEY>' aispace-client npx -- -y @aispace-sh/cliInstall aispace MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"aispace-client": {
"command": "npx",
"args": [
"-y",
"@aispace-sh/cli"
],
"env": {
"AISPACE_KEY": "<YOUR_AISPACE_KEY>"
}
}
}
}Configuration
AISPACE_KEYRequiredSecretScoped aispace bot key (ask_...).
AISPACE_ALLOWED_ROOTSOptional platform path-list restricting local file access.
AISPACE_URLOptional aispace service origin; defaults to https://aispace.sh.
Automated checks
Ran Nov 12, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubaispace.sh is a bot-friendly file drop for outputs that are too large, structured, or temporary for chat. The open-source client is deliberately easy to automate: one binary, stable exit codes, streaming uploads, and share URLs printed on a predictable final line.
- Built for agents: stable JSON on supported commands, documented errors, stdin support, and explicit noninteractive flags for automation. Secret-bearing handoff commands remain interactive.
- Short-lived by design: file expiration, separately expiring links, revocation, and optional per-link download caps.
- Private when needed: sealed asynchronous transfers encrypt filenames, file metadata, and content locally; their master key never reaches aispace. The existing age X25519 flow remains available for recipient-key workflows.
Sealed transfers, agent identities, device pairing, and adaptive durable-first intent are experimental surfaces. Ordinary uploads and durable R2 storage continue to work alongside them.
The hosted service is operated separately. This repository contains the client, agent skill, and integration examples—not the server, billing system, deployment configuration, or customer data.
Try it in 60 seconds
Install the latest release:
curl -fsSL https://aispace.sh/install.sh | sh
Authenticate with a key created in the aispace dashboard, then store a file:
aispace login --key ask_...
aispace upload report.pdf --json
On a Pro account, add a separately expiring public handoff:
aispace upload report.pdf --link --link-expires 1h --max-downloads 1
The URL is printed last on its own line, making it easy for an agent or shell script to capture.
Add --json for a stable machine-readable response. An abridged response looks like:
{"file":{"id":"...","name":"report.pdf"},"link":{"url":"https://aispace.sh/d/...","expires_at":1757003600}}
Other installation channels:
npm install -g @aispace-sh/cli
brew install aispace-sh/tap/aispace
go install github.com/aispace-sh/aispace-client@latest
Pin the shell installer with AISPACE_VERSION=v1.2.3. Release binaries support macOS, Linux, and
Windows on amd64 and arm64. The shell installer supports macOS and Linux; use npm on Windows.
Give aispace to an agent
The repository includes a reusable Codex-compatible skill. Clone the repository and link the skill into your personal Codex skills directory:
git clone https://github.com/aispace-sh/aispace-client.git
mkdir -p ~/.codex/skills
ln -s "$PWD/aispace-client/skills/aispace" ~/.codex/skills/aispace
Restart Codex, then ask it to use aispace when it needs to hand you a report, archive, image, or
other generated artifact. The skill defaults to account-private storage unless you request a public
link, prefers short expirations, and treats encryption identities as credentials.
Model Context Protocol (MCP)
The native CLI also exposes ten typed MCP tools over local stdio. Create a separately scoped bot key in the dashboard, export it in the environment that launches Codex, and add:
[mcp_servers.aispace]
command = "aispace"
args = ["mcp", "serve"]
env_vars = ["AISPACE_KEY", "AISPACE_URL", "AISPACE_ALLOWED_ROOTS"]
startup_timeout_sec = 10
tool_timeout_sec = 120
default_tools_approval_mode = "writes"
[mcp_servers.aispace.tools.aispace_create_link]
approval_mode = "prompt"
[mcp_servers.aispace.tools.aispace_revoke_link]
approval_mode = "prompt"
[mcp_servers.aispace.tools.aispace_delete_file]
approval_mode = "prompt"
Run codex mcp list to verify the connection. The ChatGPT desktop app, Codex CLI, and Codex IDE
extension on the same host share this configuration. Keep the key in a secret store or injected
environment; never put its expanded value in a committed project file or command argument. See
docs/CLI.md for Claude Code and generic-host examples.
For custom agent runtimes, docs/LLM_USAGE.md includes a system-prompt snippet,
OpenAI/Anthropic-compatible tool schemas, and a reference Python handler. See examples
for runnable shell, CI, and encrypted-handoff recipes.
Common workflows
# Upload text from stdin and return an expiring public link (Pro).
echo "hello" | aispace upload - --name note.txt --link --link-expires 1h
# Keep a file available only to this key.
aispace upload secret.txt --private
# Share ciphertext; keep the generated age identity locally.
aispace upload secret.pdf --encrypt --identity-out secret.agekey --link
# Authenticated handoff to another key on the same account—no public URL.
aispace upload notes.md --shared --json
# Sealed multi-file handoff. The URL fragment holds the local decryption secret.
aispace transfer create report.pdf charts.png --sealed --link --expires 1d --max-downloads 1
# Move that sealed transfer to a nearby browser/device with an expiring code.
aispace handoff offer "$TRANSFER_ID"
# On the receiving CLI: aispace handoff receive J7KM-PQRT
# Pin an agent and deliver without exposing a bearer decryption link.
aispace recipient add "$RECIPIENT_INVITATION"
aispace recipient verify research-agent --fingerprint "$RECIPIENT_FINGERPRINT"
aispace transfer create report.pdf --sealed --to research-agent --from my-agent --expires 7d
aispace inbox receive "$DELIVERY_ID" --yes
# Paste the link interactively, inspect its private manifest, then decrypt and verify.
aispace transfer receive
# Receive, manage, and revoke.
aispace ls --json
aispace download <file_id> --output ./file
aispace download <file_id> --output ./file --verify # check the recorded SHA-256
aispace link <file_id> --expires 30m --max-downloads 1
aispace revoke <link_id>
aispace rm <file_id>
Follow docs/SECURE_HANDOFFS.md for sealed bundles, trusted agent
inboxes, device pairing, adaptive R2 fallback, and recovery. The complete command reference is in
docs/CLI.md; the HTTP contract is in docs/API.md.
upload accepts --name, --expires, --content-type, --sha256, --link, --link-expires,
--max-downloads, --private, --shared, --encrypt, --recipient, and --identity-out.
Uploads stream from disk. Encrypted uploads use age X25519 locally and store ciphertext as
<name>.age; the secret identity is never sent to the API.
transfer create uses aispace-sealed-v1: AES-256-GCM authenticated chunks and an encrypted
manifest support multiple files, ranged retry, and a verified receipt. transfer receive accepts
the secret from its prompt, --token-file, or AISPACE_TRANSFER_TOKEN; avoid putting a full
fragment link or token in a process argument on shared systems.
transfer create --json omits bearer links and tokens unless --include-secret is explicit, and
secret-inclusive JSON must be redirected rather than written to a terminal. handoff encode
likewise accepts the protected prompt, --token-file, or AISPACE_TRANSFER_TOKEN.
With --json, errors also remain structured and are written to stderr. upload --link --json
returns {"file": File, "link": ShareLink}; encrypted uploads add an "encryption" object.
Configuration
Precedence: flag > environment > config file > default.
| Setting | Flag | Env | File key | Default |
|---|---|---|---|---|
| API key | --key |
AISPACE_KEY |
key |
— |
| Server | --url |
AISPACE_URL |
url |
https://aispace.sh |
AISPACE_AGE_IDENTITY supplies a decryption identity when decrypt --identity-file is omitted.
It is deliberately not accepted as a command-line value.
Config file: $XDG_CONFIG_HOME/aispace/config.json (default ~/.config/aispace/config.json), written with
mode 0600. A warning is printed if the file is readable by others. AISPACE_CONFIG overrides the path.
Durations (--expires, --link-expires) accept Go syntax plus a d suffix: 30m, 24h, 7d, 1d12h,
or a bare number of seconds. Omitting them uses the server defaults (7 days for files, 1 hour for
Pro public links).
File permissions and links
File visibility controls authenticated key access. A public link is a separate capability: creating one requires a Pro account and makes that one file available to anyone holding the URL.
| File mode | Who can access it? | File lifetime | Public-link lifetime | Download cap | Exposure if access leaks |
|---|---|---|---|---|---|
private |
Uploading key only | 7 days by default; maximum 7 days on Free or 30 days on Pro | None | Account monthly limit | Private files belonging to that key, until deletion or expiry |
account |
Every active key on the account | 7 days by default; maximum 7 days on Free or 30 days on Pro | None | Account monthly limit | Account-shared files, until deletion or expiry |
private + public link |
Uploading key and anyone with the URL | Maximum 30 days because links require Pro | 1 hour by default; maximum 30 days and never beyond file expiry | Optional per-link cap | Only the linked file, until link expiry, revocation, exhaustion, file deletion, or file expiry |
account + public link |
Account keys and anyone with the URL | Maximum 30 days because links require Pro | 1 hour by default; maximum 30 days and never beyond file expiry | Optional per-link cap | URL access ends with the link; account keys retain access until file deletion or expiry |
| Client-encrypted file | Visibility controls ciphertext access; only age identity holders can decrypt it | Same limits as the selected file mode | Same Pro-only limits when a link is created | Optional per-link cap | Plaintext exposure requires both the ciphertext and the age identity |
Available duration syntax includes 30s, 15m, 1h, 36h, and 7d.
A file becomes unavailable when its file lifetime ends. A link can end sooner because it expired, was revoked, or reached its download cap. Deleting the file immediately ends authenticated key access and every associated public link.
Exit codes
| Code | Meaning |
|---|---|
| 0 | success |
| 1 | generic error (network, 4xx/5xx not listed below) |
| 2 | usage error |
| 3 | authentication (401, or no key configured) |
| 4 | quota / size (402, 413) |
| 5 | rate limited (429) — idempotent GETs sleep Retry-After (max 30s) and retry once |
Errors go to stderr as error: <message> (<code>); with --json they are a JSON object
{"error":{"code","message","status","details","exit_code"}} on stderr instead.
Development
go test -race ./... && go vet ./... && test -z "$(gofmt -l .)"
go build -ldflags "-X main.version=0.0.0-dev" -o aispace .
(cd npm && npm test && npm pack --dry-run)
The test suite uses local HTTP fixtures and does not require an aispace key. Contributions are
welcome—start with CONTRIBUTING.md, check the ROADMAP.md, and
review the CHANGELOG.md. Focused bug reports and feature proposals can use the
repository's structured issue forms.
Releases are cut through the manual GitHub Actions workflow. GoReleaser builds checksummed macOS,
Linux, and Windows binaries, updates the Homebrew tap, publishes @aispace-sh/cli to npm, verifies
the installed MCP server on all three platforms, and finally publishes sh.aispace/mcp to the
official Registry. See RELEASE.md for publisher configuration, resumable MCP-only
publication, and the release checklist.
Security
Please report vulnerabilities privately through GitHub Security Advisories. Do not open a public
issue containing a credential, private link, or customer data. See docs/SECURITY.md.
aispace MCP questions
How do I add aispace MCP to Claude Code?
Run claude mcp add --env 'AISPACE_KEY=<YOUR_AISPACE_KEY>' aispace-client -- npx -y @aispace-sh/cli in your terminal. Add --scope user to make it available in every project.
How do I add aispace MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
How do I use aispace with an MCP client?
You can expose ten typed MCP tools over local stdio by running the command 'aispace mcp serve' and configuring your environment with the necessary API keys.
Is the file sharing secure for AI agents?
Yes, it supports sealed asynchronous transfers that encrypt filenames, metadata, and content locally so the master key never reaches the server.
Can I automate file uploads with JSON output?
Yes, using the --json flag provides a stable, machine-readable response that is easy for agents or shell scripts to capture.
How long do files stay available?
Files expire based on their lifetime settings, which default to 7 days, but can be configured for different durations.