MCPocket
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
MCPocket
Persistent storage and coordination for AI agents. Your agents. Your data. One shared workspace. — mcpocket.io
Persistent JSON collections
Hierarchical folders and tubes
MCP-native agent access
REST API integrations
Real-time monitoring dashboard
Folders organise tubes; tubes hold JSON items that agents claim, heartbeat and complete under a lease. Everything — web dashboard, REST API and MCP server (Streamable HTTP, legacy SSE, stdio proxy) — runs in one Next.js process sharing the same application services, so the rules, permissions and audit history are identical on every surface.

Repository layout
MCPocket is open source under the Apache License 2.0. This repository is the self-hosted edition; MCPocket Cloud is built from the same core in a separate, private repository.
Path | What it is |
| |
| The self-hosted Next.js app: dashboard, API routes, admin login |
| stdio proxy, seed and migration scripts, demo data |
npm workspaces link packages/core into the app; npm install at the root
sets everything up. App code imports the core as @mcpocket/core/....
Related MCP server: Bcontext
Quick start (Docker Compose)
Requirements: Docker with Compose v2.
git clone <repo-url> mcpocket && cd mcpocket
cp .env.example .env
# edit .env — at least (paste literal values; .env does not run commands):
# MCPOCKET_ADMIN_PASSWORD=<strong password> (required)
# MCPOCKET_API_KEYS=ops:<output of: openssl rand -hex 24> (REST / MCP clients)
# MCPOCKET_SESSION_SECRET=<output of: openssl rand -base64 32>
docker compose up -d --build
docker compose ps # STATUS shows "(healthy)" after a few secondsThen open http://localhost:3000 and sign in at /login with
MCPOCKET_ADMIN_USERNAME (default admin) / MCPOCKET_ADMIN_PASSWORD.
Check the API with the key from .env:
curl http://localhost:3000/api/health # {"status":"ok",...} (no auth)
curl -H "Authorization: Bearer <secret>" http://localhost:3000/api/folders/treeWhat you get:
Image |
|
Service |
|
Volume |
|
Seed | with |
Health |
|
Workers | lease sweeper + webhook dispatcher start inside the same process ( |
Initial admin account. There is one dashboard admin, defined by
MCPOCKET_ADMIN_USERNAME / MCPOCKET_ADMIN_PASSWORD in .env — no setup
wizard, nothing stored in data/. Compose refuses to start while the
password is empty. To change it, edit .env and docker compose up -d
(existing sessions are invalidated). .env.example sets
MCPOCKET_COOKIE_SECURE=false so sign-in works over plain
http://<host>:3000; put MCPocket behind an HTTPS reverse proxy and set it
to true for anything beyond a local/trusted network. API keys: env keys
from MCPOCKET_API_KEYS, or create scoped keys on the dashboard Access
page.
Configuration. Every variable is documented in
.env.example (storage, seeding, admin, API keys/roles,
rate limits, leases/retries/sweeper, agent monitoring, webhooks). Details per
feature are in the sections below.
Operations.
docker compose logs -f mcpocket # logs (seeding, sweeper, dispatcher)
git pull && docker compose up -d --build # upgrade — data stays on the volume
docker compose down # stop (keeps the volume)
docker compose down -v # stop AND delete all dataRun exactly one replica. Writes are serialised by an in-process lock (both storage drivers), and the sweeper/dispatcher/rate limiter/SSE sessions are in memory: never scale the service or point two containers at the same volume.
The container needs outbound HTTP(S) to your webhook URLs.
A bind mount instead of the named volume (
./data:/app/data) works too; the directory must be writable by uid 1000 (sudo chown 1000:1000 data).
Storage drivers
STORAGE_DRIVER selects where data lives. json and sqlite run inside the
one Node process — no database container; mongo uses an external MongoDB:
Driver | Data | Notes |
| one file per collection in | everything in memory; each write rewrites the touched files. Simple to read/diff; best for small datasets |
| one file, | built-in |
| workspace | one collection per entity, documents are the entities themselves (plus a |
One database and one bucket, many workspaces. MCPOCKET_WORKSPACE
(default MCPOCKET_SSO_WORKSPACE; slug: letters, digits, _, ., -)
names the tenant an instance serves. Every Mongo document carries a
workspace field and every query is scoped to it ({workspace, id} is
unique, so workspaces may reuse entity ids; without a workspace the Mongo
driver uses default), and media objects live under
<MCPOCKET_MEDIA_PREFIX><workspace>/, so many MCPocket instances — one per
workspace, as on MCPocket Cloud — can share one database and one bucket.
Cloud mode (MCPOCKET_MULTI_WORKSPACE=true, needs mongo): instead of
one instance per workspace, ONE instance serves every workspace and each
request acts in the workspace of its credential:
Credential | Workspace |
Dashboard SSO session | the sign-in token's |
OAuth access token | the grant's |
Managed API key | the workspace it was created in |
Password admin, env API keys |
|
Storage, media prefix, live dashboard events, signed upload links and media
access are all scoped to that workspace; the lease sweeper and webhook
dispatcher run over every workspace. With MCPOCKET_SEED_ON_FIRST_START, a
workspace is seeded the first time it is used. Try it locally:
npm run sso:token -- you@example.com --ws acme.
With mongo, npm run seed and MCPOCKET_SEED_ON_FIRST_START (fills an
empty workspace) work as for the other drivers but only touch the instance's
own workspace, and a running server sees a re-seed at once. The Mongo tests run against a real server when
MONGODB_TEST_URI is set (each test uses a throwaway mcpocket_test_*
database).
Production with MongoDB
docker-compose.prod.yml runs the app together with MongoDB 8 as a
single-node replica set, so every commit is a MongoDB transaction:
# .env: MCPOCKET_ADMIN_PASSWORD, MONGO_ROOT_PASSWORD, MONGO_APP_PASSWORD (+ app secrets)
docker compose -f docker-compose.prod.yml up -d --build # or: make up PROD=1The app connects with its own readWrite account (created on first start by
docker/mongo/initdb.d/01-app-user.js), never the root user. MongoDB is not
published publicly, only on 127.0.0.1:${MONGO_PORT:-27017} for admin over an
SSH tunnel (use ?directConnection=true from there). Data lives in the
mongo-data / mongo-config volumes; the header of the compose file has a
mongodump backup command.
Data written before workspaces existed has no workspace field and is
invisible to the app. Assign it to a workspace once (mongosh, as a
readWrite user of the database), then restart:
for (const c of ["folders", "tubes", "items", "history", "api_keys", "audit", "webhooks", "webhook_deliveries"])
db[c].updateMany({ workspace: { $exists: false } }, { $set: { workspace: "default" } })
db.counters.find({ _id: { $not: /:/ } }).forEach((c) => {
db.counters.insertOne({ _id: `default:${c._id}`, seq: c.seq }); db.counters.deleteOne({ _id: c._id })
})Switch an existing JSON dataset to SQLite (the JSON files are left as they are):
# stop the server first
npm run migrate:sqlite # copies DATA_DIR/*.json → mcpocket.db (refuses a non-empty DB; --force to replace)
STORAGE_DRIVER=sqlite npm run dev # or set STORAGE_DRIVER=sqlite in .env / docker-compose.ymlIn Docker set STORAGE_DRIVER: sqlite in docker-compose.yml; a fresh
volume is seeded into the database on first start, like the JSON driver. To
move an existing volume, copy its data out (docker compose cp mcpocket:/app/data ./data-export), run DATA_DIR=./data-export npm run migrate:sqlite on the host, copy data-export/mcpocket.db back in, then
switch the driver. Node prints a one-time
ExperimentalWarning: SQLite is an experimental feature at startup; it is
harmless.
Backup & restore
SQLite: the database is mcpocket.db plus its -wal/-shm files —
copy all three with the app stopped (same commands as below), or take a live
snapshot with sqlite3 data/mcpocket.db ".backup backup.db".
JSON: all state lives in the data directory (folders.json, tubes.json,
items.json, history.json, api-keys.json, audit.json,
webhooks.json, webhook-deliveries.json). Files are replaced atomically
(write temp + rename), but stop the app for a consistent snapshot across
files:
# backup
docker compose stop mcpocket
docker compose cp mcpocket:/app/data ./backup-$(date +%F)
docker compose start mcpocket
# restore (replaces the current data)
docker compose stop mcpocket
docker compose cp ./backup-2026-01-31/. mcpocket:/app/data/
docker compose start mcpocket(docker compose cp works on stopped containers. Without Docker: copy
DATA_DIR, default ./data, while the server is stopped.) To reset to the
demo data, stop the app, empty the volume (docker compose down -v) and
start again with MCPOCKET_SEED_ON_FIRST_START=true.
Local development
npm install
cp .env.example .env.local # set MCPOCKET_ADMIN_PASSWORD and MCPOCKET_API_KEYS
npm run seed # (re)seed storage from mock/seed.json — JSON: restart the server afterwards; SQLite: live
npm run dev # http://localhost:3000
npm test && npm run typecheck && npm run lintnpm run build && node .next/standalone/server.js runs the production
bundle (copy public/ and .next/static/ next to it first, as the
Dockerfile does). npm run build:stdio bundles the stdio proxy into a
single dependency-free file (dist/mcpocket-stdio.mjs, shipped in the image
as bin/mcpocket-stdio.mjs).
Dashboard (admin login)
The web dashboard lives at /dashboard (landing page at /, sign-in at
/login). It is protected by a single admin account configured through the
environment; the browser only receives an httpOnly, HMAC-signed session
cookie (mcpocket_session) — never an API key. The dashboard calls the same
application services as REST/MCP, so audit history records it as
user:<username>.
Variable | Default | Purpose |
|
| Admin login name |
| — (required) | Admin password. Without it the login page shows setup instructions and nobody can sign in |
| derived from the password | Key for signing session cookies ( |
|
| Session lifetime |
|
| Set |
|
| Agents page: an agent is online if its last heartbeat (or any other call) is at most this old |
|
| Agents page: older than online but at most this old = idle; older (or never seen) = stale. Must exceed the online threshold |
|
| Failed logins allowed per client IP (first |
|
| Login throttling window; a successful login resets the client's counter |
Changing the username, password or session secret invalidates existing
sessions. Example .env.local:
MCPOCKET_ADMIN_USERNAME=admin
MCPOCKET_ADMIN_PASSWORD=change-me
MCPOCKET_SESSION_SECRET=<output of: openssl rand -base64 32>SSO token login (optional)
A trusted external system — MCPocket Cloud's control plane, or your own
identity provider — can sign a person into the dashboard without a password.
It sends the browser to /auth/sso?token=<jwt> (or POSTs a form with a
token field); next=/dashboard/... optionally picks the landing page. A
valid token starts a normal dashboard session (same cookie, same TTL) with the
person's email as username, so audit history records user:<email>. SSO
users act as administrators, like the password account. Password login keeps
working. The feature is off — /auth/sso returns 404 — unless
MCPOCKET_SSO_SECRET is set.
Variable | Default | Purpose |
| — (SSO off) | Shared HMAC key the issuer signs tokens with ( |
| — | When set, a token's |
The token is a compact JWT, HS256 (HMAC-SHA256 with MCPOCKET_SSO_SECRET):
{ sub: "ada@example.com", // email → session username (lower-cased)
ws?: "acme", // must match MCPOCKET_SSO_WORKSPACE when that is set
jti: "<unique id>", // single use
iat: 1767225600,
exp: 1767225660 } // at most 60 s after iatTokens with a bad signature, another algorithm, an expired or overly long
lifetime, no valid sub, the wrong workspace or an already used jti are
rejected: the browser lands on a short error page (/auth/sso/error) with a
link back to sign in, and no session is created. Used jtis are remembered
in memory until they expire (one replica per instance).
To try it by hand without the cloud, set MCPOCKET_SSO_SECRET in
.env.local, start the server and mint a single-use link (valid 60 s):
npm run sso:token -- ada@example.com # or: make sso-token EMAIL=ada@example.com
# options: --ws <slug> --ttl <seconds> --next /dashboard/agents --url http://localhost:3000SSO-only mode (managed instances)
An instance run by MCPocket Cloud (or behind your own identity provider) can
hand sign-in entirely to the external system. All three variables are
optional; with none of them set, /login, the dashboard redirect and sign-out
behave as described above.
Variable | Default | Purpose |
| — | Absolute |
|
| Absolute |
| enabled |
|
URLs that are not absolute http(s) URLs, or that embed credentials, are
ignored (with a warning in the server log), as is a login URL pointing back at
this instance's own /login or /dashboard. When /login is shown without a
usable password login but with SSO configured, it explains that the dashboard
uses single sign-on instead of showing the setup instructions. While
MCPOCKET_SSO_LOGIN_URL is set the password form is not reachable; unset it
to sign in with the admin password.
A typical managed instance:
MCPOCKET_SSO_SECRET=<shared with the control plane>
MCPOCKET_SSO_LOGIN_URL=https://cloud.example/sso/acme
MCPOCKET_PASSWORD_LOGIN=falseThe left sidebar holds the folder explorer: expand/collapse folders (state is
remembered), and use the … menu on a folder or tube to create subfolders and
tubes, rename, move or delete. Service errors (validation, moving a folder
into its own subtree, deleting a non-empty folder/tube) are shown in the
dialog. Press d to toggle dark mode, Cmd/Ctrl+B to toggle the sidebar.
Click an item row in a tube to open the item inspector (?item=<id> in
the URL): edit the JSON payload (highlighted, validated live against the tube
schema), see result / last error, retry, cancel, archive, delete, change
status, reassign the agent, and read the full audit history. Reassigning is
also available as POST /api/items/{id}/reassign { "agentId": "bot-2" | null }
(a processing item's lease moves to the new agent; history action
reassigned).
Agents. /dashboard/agents lists every known agent (assigned / processing /
completed / failed counts, last heartbeat, availability); each agent page lists
its assigned items, linking into the tube view filtered by the agent with the
inspector open.
Real-time updates. The dashboard keeps one Server-Sent Events connection
open (GET /api/dashboard/events, session cookie only — API keys are
rejected) and re-renders counters, item rows, the inspector and the folder
tree whenever an item, tube or folder changes — whether via REST, MCP or
another browser tab. The header shows Live / Reconnecting…; the stream
reconnects automatically and catches up after an outage. If the payload you
are editing changes elsewhere, your unsaved text is kept and a "changed
elsewhere" hint offers to load the latest version. Scope with ?tubeId=<id>
or ?itemId=<id> (folder/tube events are always included); events are
event: domain with JSON {seq, type, at, actor, …} (item.created,
item.updated, item.status_changed, item.deleted, folder.*, tube.*)
and a : ping comment every 15 s.
Connecting MCP clients
MCPocket's MCP server (name: "mcpocket") runs inside the Next.js app and
shares its application services with the REST API. Every transport requires
an API key (from MCPOCKET_API_KEYS or created on the dashboard's Access
page — see Permissions & rate limiting), sent as
Authorization: Bearer <secret> (or X-API-Key). Add X-Agent-Id: <id> to
act as a named agent. Tool errors come back as MCP tool errors with the REST
error body { "error": { "code", "message", "details"? } }.
Transport | Endpoint |
Streamable HTTP (stateless, JSON responses) |
|
Legacy HTTP+SSE (older clients) |
|
stdio |
|
Streamable HTTP (e.g. Claude Code):
claude mcp add --transport http mcpocket http://localhost:3000/api/mcp \
--header "Authorization: Bearer $MCPOCKET_API_KEY"Legacy SSE:
claude mcp add --transport sse mcpocket http://localhost:3000/api/mcp/sse \
--header "Authorization: Bearer $MCPOCKET_API_KEY"stdio (e.g. Claude Desktop claude_desktop_config.json). The stdio process
never opens data/ itself (v1 JSON storage is single-process): it is a thin
proxy that relays MCP messages to the running app's /api/mcp endpoint, so
the app must be running.
{
"mcpServers": {
"mcpocket": {
"command": "node",
"args": ["/path/to/mcpocket/bin/mcpocket-stdio.mjs"],
"env": {
"MCPOCKET_URL": "http://localhost:3000",
"MCPOCKET_API_KEY": "<secret>",
"MCPOCKET_AGENT_ID": "my-agent"
}
}
}
}(npm run --silent mcp:stdio works too; without --silent npm's banner would
corrupt the stdio protocol stream.)
stdio with Docker (no local Node.js / checkout needed): the image ships
the proxy as a single file. Run it inside the running container — it talks
to the app over localhost:
{
"mcpServers": {
"mcpocket": {
"command": "docker",
"args": ["compose", "-f", "/path/to/mcpocket/docker-compose.yml",
"exec", "-T",
"-e", "MCPOCKET_API_KEY=<secret>", "-e", "MCPOCKET_AGENT_ID=my-agent",
"mcpocket", "node", "bin/mcpocket-stdio.mjs"]
}
}
}(or docker run -i --rm --add-host=host.docker.internal:host-gateway -e MCPOCKET_URL=http://host.docker.internal:3000 -e MCPOCKET_API_KEY=… mcpocket:latest node bin/mcpocket-stdio.mjs).
Scoped connections (one tube or one folder): bind a connection to a single tube or a folder subtree — useful for an agent that should only work one queue or one project, with any API key that can reach it:
Transport | Tube | Folder (with everything below it) |
Streamable HTTP |
|
|
Legacy HTTP+SSE |
|
|
stdio (proxy env) |
|
|
Tube: the session sees only that tube (others are 404); every
tubeIdargument is optional and defaults to it; folder tools andcreate_tube/move_tube/delete_tubeare not offered.Folder: the session sees the folder, its subfolders and their tubes (ancestor folders by name only, everything else is 404);
create_folderandcreate_tubedefaultparentId/folderIdto the folder; the bound folder itself cannot be deleted or moved (403).The key must fully reach the target (404, or 403 for a folder that is only an ancestor of the key's own scope), so binding can only narrow access. Admin keys act as
operatoron scoped connections; other roles keep their capabilities.
The dashboard's MCP page (also Connect via MCP in the folder/tube menus and the MCP button on a tube) generates ready-to-paste client configs for any folder or tube. For a hard per-key restriction, give the key a scope on the Access page.
Agent work loop: claim_next_item → heartbeat_item (before the lease
expires) → complete_item | fail_item | release_item. The agent identity is
the session's X-Agent-Id / MCPOCKET_AGENT_ID — never a tool argument — and
lease rules match the REST API. Other item tools: push_item, get_item,
update_item, delete_item, list_items, search_items, bulk_push_items,
bulk_update_items, get_my_items, get_item_history (filters and bulk
rules: see "Search, filtering & bulk operations" below).
Resources: mcpocket://system/info, mcpocket://folders/tree,
mcpocket://tubes/{id} (settings + JSON Schema + item count; listed per tube)
and mcpocket://items/{id} (item + 20 latest history events).
OAuth clients (ChatGPT connectors)
Some MCP clients — ChatGPT connectors in particular — cannot send an API key:
they sign in with OAuth and send an access token instead. Set
MCPOCKET_OAUTH_ISSUER and the MCP endpoints also accept OAuth access tokens
(signed JWTs) from that authorization server, verified against its JWKS
(RS256 / ES256 / EdDSA; keys cached 10 minutes, refetched on rotation):
/.well-known/oauth-protected-resource(and the per-endpoint form/.well-known/oauth-protected-resource/api/mcp[/tubes/<id>|/folders/<id>], RFC 9728) names the authorization server;an MCP request without a valid token answers
401withWWW-Authenticate: Bearer resource_metadata="<that URL>", which is how ChatGPT discovers where to sign in.
Authorization is a claim, not the sign-in itself. A valid signature is not enough: the token must carry a grant for this workspace, added by the authorization server (MCPocket Cloud: a Supabase custom access token hook, filled by its consent page):
"mcpocket": { "ws": "<workspace slug>", "role": "readonly" | "agent" | "operator" }ws must equal MCPOCKET_OAUTH_WORKSPACE (one connection = one workspace),
and admin is never accepted over OAuth. The request acts as the agent
oauth:<email> (or X-Agent-Id) with that role and no scope. API keys keep
working unchanged; upload links (create_media_upload) still need an API key.
Variable | Default | Meaning |
| — | Exact |
|
| Signing keys |
| not checked | Required |
|
| Slug the grant must name; unset = any |
|
| Name of the grant claim |
Search, filtering & bulk operations
REST GET /api/tubes/{id}/items and the MCP tools list_items (per tube) /
search_items (tubeId optional → all tubes) accept the same filters. All
given filters must match (AND); they are evaluated in memory, then paginated
(offset, limit ≤ 1000; page.total = number of matches; oldest first).
Filter | Meaning |
| one status, an array or a comma list ( |
| exact agent id |
| inclusive bounds; ISO datetime, or |
| exact / inclusive range |
| item must carry all listed tags (array or comma list) |
| also return soft-deleted items |
| payload field conditions (below) |
Payload conditions — MCP / JSON: payload: [{ "path": "customer.address.city", "op": "eq", "value": "Berlin" }].
REST query: payload.<path>=<value> (equality) or payload.<path>[<op>]=<value>,
e.g. ?payload.customer.address.city=Berlin&payload.total[gte]=100&payload.kind[in]=a,b.
Query values that parse as JSON scalars become numbers / booleans / null.
path is dotted; numeric segments index arrays (lines.0.sku).
| Matches when the field… |
| deep-equals |
| is not |
| compares: numbers numerically (numeric strings coerced), strings lexically (ISO dates work); missing/other types never match |
|
|
| string: case-insensitive substring; array: has an element |
| is present ( |
Bulk operations (≤ 500 entries; REST body ≤ 5 MiB → else 413
payload_too_large; more entries → 400). Each runs in one storage
transaction (one write-lock hold, persisted once). Every entry follows the
single-item rules and gets its own result; an invalid entry does not stop the
others. Response: { results: [{ index, ok: true, data, created? } | { index, ok: false, id?, error: { code, message, details? } }], summary: { total, succeeded, failed, created? } }.
POST /api/tubes/{id}/items/bulk/bulk_push_items—{ items: [{ payload, priority?, tags?, metadata?, idempotencyKey? }] }. Idempotency keys are honoured (also within one batch:created: false), payloads validated against the tube schema.PATCH /api/items/bulk/bulk_update_items—{ items: [{ id, payload?, metadata?, tags?, priority?, status? }] }or{ ids: [...], patch: { ... } }. Same manual status transitions and history events asPATCH /api/items/{id}.
Tube reset: POST /api/tubes/{id}/reset (needs items:manage; also the
Reset button in the tube view) → { data: { total, matched, requeued } }.
The optional body takes the item search filters (status, assignedAgent,
createdFrom/createdTo, priority/priorityMin/priorityMax, tags,
payload conditions) to limit which items are reset — e.g.
{ "status": "failed" } or { "status": ["failed", "cancelled"] }; no body
resets every item. Each matching non-deleted item — whatever its status,
including processing, completed and archived — goes back to a fresh
pending: assignment and active leases are revoked, and attempts, backoff,
result, last error and completion time are cleared. Payload, metadata, tags
and priority are kept. One transaction; each changed item gets a reset
history event.
Tube clone: POST /api/tubes/{id}/clone { name?, folderId?: id|null, includeItems? } (needs structure:manage, plus items:push with items; also
Clone in the tube's … menu) → 201 { data: Tube, items }. Copies
description, enabled, schema and retry policy; the name defaults to
"<name> (copy)" and the folder to the source's. With includeItems: true
every non-deleted item is copied as a fresh pending item (payload, metadata,
tags, priority, idempotency key); results, errors and history are not copied,
and each copy's created event records clonedFrom.
Statistics & monitoring
REST (API key required) and MCP tools return identical shapes:
REST | MCP tool | Returns |
|
|
|
|
|
|
|
| page of |
|
| page of |
counts = { total, pending, processing, completed, failed, retry, cancelled, archived } over non-deleted items. Agent completed/failed come from the audit history (events written by that agent); assigned/processing from items currently attributed to it.
Retries & lease sweeper
Every claim increments item.attempts. When an agent calls fail (REST
POST /api/items/{id}/fail, MCP fail_item) and the tube's retry policy has
attempts left, the item goes to retry with retryAt = now + backoff; claim
skips it until then. On the last attempt it stays failed. History: failed
with newValue { status: "retry" | "failed", retryAt?, maxAttempts, error }.
A background lease sweeper (started from instrumentation.ts when the
server boots; not during next build; one per process) periodically recovers
items whose lease expired because the agent died: attempts left → retry
(claimable immediately), exhausted → failed; lastError.code =
lease_expired, history action lease_expired by system:lease-sweeper,
and the dashboard updates live. Claims run the same recovery for their tube
first, so nothing waits for the next sweep. Any manual status change (e.g.
retry → pending in the dashboard) drops the backoff delay.
Per-tube overrides: retryPolicy on tube create/update (REST, MCP
create_tube/update_tube, dashboard tube Settings) —
{ maxAttempts?, backoff?: "fixed" | "exponential", delaySeconds?, maxDelaySeconds? };
missing fields use the defaults below, null or {} clears all overrides.
Exponential delay = delaySeconds × 2^(attempt − 1), capped at maxDelaySeconds.
Variable | Default | Purpose |
|
| Default lease duration for claim / heartbeat |
|
| Total attempts (claims) per item; |
|
|
|
|
| Base retry delay |
|
| Cap for the exponential delay |
|
|
|
|
| Seconds between sweeps (1..3600) |
Permissions (RBAC) & rate limiting
Every REST request, MCP call (Streamable HTTP, legacy SSE, stdio proxy) and dashboard action goes through the same application services, which check the caller's role and scope — so the rules are identical on every surface.
Role | May |
| everything, everywhere, incl. API keys / permissions and the access audit log |
| read; push, update, delete, reassign items; claim/process; manage folders & tubes |
| read; push items; claim → heartbeat → complete / fail / release |
| read folders, tubes, items, history, statistics |
A missing capability → 403 forbidden (details: { capability, role }).
MCP tools/list only advertises the tools the caller's role allows.
Scope (non-admin keys): a list of folders and/or tubes. A folder grants
everything below it (subfolders and tubes, including ones created later).
Outside the scope, entities are invisible: lists, search, the folder tree,
statistics and MCP resources only contain what the key can see, and direct
access returns 404 not_found. Ancestor folders of the scope stay visible
(names only, for navigation) but cannot be changed (403).
Keys. Two sources:
MCPOCKET_API_KEYS="keyId:secret,..."— read-only config. Existing keys keep full access: their role defaults toadmin(MCPOCKET_API_KEY_DEFAULT_ROLE), and can be set per key withMCPOCKET_API_KEY_ROLES="ci:readonly,bots:agent". Env keys are unscoped.Managed keys — dashboard Access page (or
POST /api/keys, admin): id, role, scope, optional bound agent identity (the key always acts as that agent; a differentX-Agent-Id→ 403) and optional per-key rate limit. The secret (mcp_…) is shown once on creation/rotation; only its SHA-256 is stored (data/api-keys.json). Keys can be edited, rotated, revoked (rotate re-activates) and deleted. Role/scope changes apply to the next request (also to open SSE sessions). Re-seeding keeps managed keys.
Every key/permission change is written to the access audit log
(data/audit.json; dashboard Access page, GET /api/audit), with the
acting admin and old → new role/scope/agent/limit — never secrets.
REST (admin) | |
| list (env + managed, no secrets) / create → |
| read / change |
| new secret |
| access audit log, newest first |
Rate limiting is per API key (agents acting through one key share its
budget), fixed one-minute windows, in memory (single process). Every
authenticated REST/MCP response carries RateLimit-Limit,
RateLimit-Remaining and RateLimit-Reset (seconds); over the limit the
response is 429 rate_limited with Retry-After. Dashboard logins are
throttled per client IP (see the Dashboard table).
Variable | Default | Purpose |
| — |
|
| — |
|
|
| Role of env keys not listed in |
|
| Requests per key per minute (managed keys may override; |
Webhooks
An admin registers webhook URLs (dashboard Webhooks page or REST) —
optionally limited to item event types (item.created, item.updated,
item.status_changed, item.deleted; empty = all) and to one folder
(its whole subtree) or one tube. MCPocket then POSTs a JSON event for
every matching item change:
{ "id": "<event id>", "type": "item.status_changed", "createdAt": "…",
"data": { "action": "completed", "actor": "agent:bot-1", "itemId": "…", "tubeId": "…",
"folderId": "…", "status": "completed", "previousStatus": "processing",
"assignedAgent": "bot-1", "item": { …item as committed… } } }Reliable delivery (transactional outbox). The delivery rows are written
in the same storage transaction as the item change (one write lock, one
persist — data/webhook-deliveries.json): if the change rolls back, no
event is queued; if the process crashes after the change, the event is still
in the outbox. A background dispatcher (started from instrumentation.ts
next to the lease sweeper; one per process; woken immediately by item
events, otherwise polling) sends due rows. 2xx = delivered; anything else
(non-2xx, redirects, network errors, timeouts) is retried with exponential
backoff and dead-lettered after the max attempts. Delivery is
at-least-once — dedupe on X-MCPocket-Delivery (per subscription) or the
payload id (per event). Deliveries of a disabled webhook wait until it is
re-enabled. Old delivered/dead rows are pruned after the retention period.
Re-seeding keeps webhook subscriptions but empties the outbox.
Signatures. Each webhook has its own secret (whsec_…), shown once
on creation / rotation (it's stored to sign, but never returned or logged
again). Headers: X-MCPocket-Signature: t=<unix>,v1=<hex> where
v1 = HMAC-SHA256(secret, "<t>.<raw body>"), plus X-MCPocket-Event,
X-MCPocket-Event-Id, X-MCPocket-Delivery, X-MCPocket-Webhook-Id,
X-MCPocket-Attempt. Verify against the raw body and reject old t
(verifyWebhookSignature in lib/webhooks/signature.ts is a reference):
const [, t, v1] = header.match(/t=(\d+),v1=([0-9a-f]+)/)
const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex")
const ok = crypto.timingSafeEqual(Buffer.from(v1, "hex"), Buffer.from(expected, "hex"))Managing webhooks needs the admin role (access:manage); every change is
in the access audit log (webhook.*, never the secret).
REST (admin) | |
| list (with pending/delivered/dead counts, no secrets) / create |
| read / change ( |
| new secret |
| queue a |
| outbox / delivery log, newest first |
| payload, status, attempt log (time, HTTP status, duration, error / response excerpt) |
| re-queue now with a fresh attempt budget (dead, delivered → redeliver, pending) |
Variable | Default | Purpose |
|
|
|
|
| Polling interval (1..3600); item events also wake it |
|
| Attempts before a delivery is dead-lettered |
|
| First retry delay; doubles per attempt |
|
| Cap for the retry delay |
|
| Per-request timeout |
|
| Deliveries sent concurrently per pass |
|
| Prune delivered/dead rows after N days ( |
Media (S3)
Items can carry images, videos and other files. The Media module keeps
the bytes in S3 (or any S3-compatible store: MinIO, Cloudflare R2, B2,
Spaces, ...) and the item keeps only the URL. It is off until
MCPOCKET_S3_BUCKET is set; while off, everything below is stored unchanged.
Embedded media. Put a file into payload or metadata as a
data URI — at any
depth, any number of them. On push, bulk push, update and bulk update (REST,
MCP, and the dashboard's Import items dialog) every data URI with an
explicit MIME type is uploaded and replaced by its public URL before the
item is stored, so items, history and webhooks never contain the bytes:
{ "payload": { "title": "Hero", "image": "data:image/png;base64,iVBORw0KGgo…",
"attachments": ["data:application/pdf;name=brief.pdf;base64,JVBERi0…"] } }
→ { "payload": { "title": "Hero", "image": "https://my-bucket.s3.eu-central-1.amazonaws.com/media/3f/3f2a….png",
"attachments": ["https://…/media/9c/9c41….pdf"] } }Objects are content-addressed (<prefix><sha256[0..2]>/<sha256>.<ext>), so
the same file is stored once and retried / idempotent pushes never create
duplicates. Every URI is checked (type, size, encoding) before the first
upload; a bad one rejects the push with 400 / 413 (in a bulk push: that
entry only). An S3 failure fails the request (500) and nothing is stored.
Uploads run before the write transaction, so a slow bucket never blocks other
writers. Plain https:// URLs are left as they are (not re-hosted).
Direct upload (needs items:push) — better for large files, since
JSON bodies carry base64 (+33 %):
curl -X POST "$URL/api/media?filename=clip.mp4" -H "Authorization: Bearer $KEY" \
-H "Content-Type: video/mp4" --data-binary @clip.mp4
curl -X POST "$URL/api/media" -H "Authorization: Bearer $KEY" -F file=@photo.jpg
# → 201 { "data": { "url", "key", "contentType", "size", "sha256", "filename"? } }
curl "$URL/api/media" -H "Authorization: Bearer $KEY" # { "data": { "enabled", "maxBytes", "allowedTypes" } }Media library (dashboard → Media): every file under the prefix,
newest first, with image / video / audio previews, totals per kind, filters
(kind, unused only), upload (several files at once), copy / open URL,
Used by (the items whose payload, metadata or result reference the file,
linked to the item inspector) and delete (warns when items still link to it).
Each tube has a Media tab next to Items with the same gallery limited
to the files its items reference (counts per file = items of that tube).
Same over REST (tubeId= for one tube):
curl "$URL/api/media/objects?tubeId=<tube id>&kind=video" -H "Authorization: Bearer $KEY"
curl "$URL/api/media/objects?kind=image&usage=unused&offset=0&limit=48" -H "Authorization: Bearer $KEY"
curl "$URL/api/media/usage?key=media/ab/ab12….png" -H "Authorization: Bearer $KEY"
curl -X DELETE "$URL/api/media/objects?key=media/ab/ab12….png" -H "Authorization: Bearer $KEY" # items:manageDemo: npm run demo:media (server running, media storage on) creates
Media Studio (demo) with a 5-stage pipeline — Prompts → Images → Videos →
Captions → Publish — through the REST API: generated PNG images, MP4 clips
animated from the image as first frame (needs ffmpeg), WAV voice-overs and
PDF briefs, handed from stage to stage by demo agents with
complete { next }. Each tube description names the next tube's id, the way
you would instruct real agents. --force creates another copy.
Listing reads the whole prefix (up to 10,000 objects) and scans items for references on each request — fine for the single-process v1 store.
Delivery. By default the links point at this server —
https://<your host>/api/media/files/media/ab/ab12….png — which streams the
file from the bucket, so the bucket can stay private and no CDN is
needed.
Access (MCPOCKET_MEDIA_ACCESS). private (default): a file opens only
for an API key with read (Authorization: Bearer …), a signed-in dashboard
session (previews just work), or a signed link. To hand a file to
something without an API key — a generator that needs an image as a video's
first frame, a social network, a player, a person — mint a temporary link
with the MCP tool create_media_link or POST /api/media/links { url | urls, expiresInSeconds? } (60 s … 7 days, default 1 h) and give out
data.link; items keep the permanent data.url. Signed links are cacheable
until they expire; key / session answers are Cache-Control: private.
public: anyone with the link (keys are sha256 content hashes, so links
cannot be guessed, but they never expire). The endpoint answers Range requests (video
seeking), HEAD, If-None-Match → 304 and caches for a year (files never
change); HTML / SVG uploads are sent as attachments under a sandbox CSP, so a
file can never run script on the dashboard origin. Set MCPOCKET_PUBLIC_URL
so links carry the public host rather than whatever host the request used.
To serve from elsewhere instead: MCPOCKET_MEDIA_PUBLIC_URL (a CDN in front
of the bucket) wins over everything, or MCPOCKET_MEDIA_DELIVERY=bucket
links straight to the bucket, which must then be readable — a public bucket /
bucket policy, or MCPOCKET_S3_ACL=public-read where ACLs are enabled.
Links already stored in items keep the form they were stored with.
Deleting an item does not delete its media.
Variable | Default | Meaning |
| — | Bucket name; set it to enable media |
|
| Region ( |
| AWS | Endpoint of an S3-compatible store, e.g. |
|
| Path-style addressing ( |
| SDK chain | Credentials; unset = |
| — | Canned ACL per upload, e.g. |
|
|
|
|
|
|
| — | Base URL of the returned links (CDN); overrides |
| request origin | This server's public base URL, used in |
|
| Key prefix; |
|
| Max size of one file (50 MiB) |
| any | MIME allowlist, comma separated, |
Request size limits still apply: bulk REST bodies ≤ 5 MiB, dashboard import requests ≤ 25 MB (one item each when larger than ~800 KB). Use direct upload for anything bigger.
Media for LLM agents (ingest & upload links)
An LLM agent cannot paste a video as base64 into a tool call, and generators
usually hand out temporary URLs (plain https URLs in items are stored as
they are, not copied). Two MCP tools cover this (items:push):
ingest_media { url }(orurls, ≤ 20; each a URL or{ url, contentType?, filename? }) — the server downloads the file into S3 and returns its permanentdata.url; per-URL results like the bulk tools. Only public hosts are fetched: private, loopback and link-local addresses are refused at connect time (redirects included). URLs already in media storage come back as they are (reused: true).create_media_upload { contentType?, filename?, expiresInSeconds? }— a signed, short-lived (default 15 min, ≤ 1 h) URL for one file from the agent's shell:curl -X PUT -H 'Content-Type: video/mp4' --data-binary @clip.mp4 <uploadUrl>→201 { data: { url, … } }(PUTorPOST /api/media/uploads/{token}, raw bytes or multipart). No API key leaves the agent; the link is bound to the key that created it, which is re-checked (revoked → 401) and rate-limited on upload. Links are signed with a key derived fromMCPOCKET_SESSION_SECRET(or the admin / SSO secret), else with a random key generated once into<DATA_DIR>/.media-upload-secret(mode 0600) — so links survive restarts either way. Instances that share neither a secret nor a data directory should setMCPOCKET_SESSION_SECRET.
Variable | Default | Meaning |
|
| Max time for one |
|
| Allow ingesting from private / loopback hosts (local dev only — SSRF risk) |
Pipelines (complete → next tube)
Chain tubes into stages — e.g. prompts → images → videos → captions →
publish — by letting the agent that completes an item push its output into
the next tube in the same call. complete_item (MCP) /
POST /api/items/{id}/complete take an optional next: one entry or a list
(≤ 100) of { tubeId, payload, priority?, tags?, metadata?, idempotencyKey? },
each following push_item's rules.
POST /api/items/<prompt item id>/complete
{ "result": { "model": "img-v2" },
"next": { "tubeId": "<images tube>",
"payload": { "prompt": "a cat on the moon", "image": "data:image/png;base64,iVBOR…" } } }
→ { "data": { …completed prompt item… },
"next": [ { "tubeId": "<images tube>", "status": "pending",
"payload": { "prompt": "…", "image": "https://…/media/ab/ab12….png" },
"metadata": { "source": { "tubeId": "<prompts tube>", "itemId": "<prompt item id>",
"root": { "tubeId": "<prompts tube>", "itemId": "<prompt item id>" } } } } ] }Atomic: completing the item and creating every
nextitem is one write. If any entry is rejected (unknown, disabled or out-of-scope tube, schema mismatch) nothing is written, the lease stays and the error names the entry (next[1]: …).Media: data URIs in
resultand innextpayload / metadata are uploaded to S3 first (see Media); a file used in several places is uploaded once.Lineage: every new item gets
metadata.source = { tubeId, itemId, root }(root= the first item of the chain, e.g. the original prompt), and the source item'scompletedhistory event lists the items it created.Hand-off targets (
nextTubeIds): a tube can declare the stages it hands off to (tube settings → Pipeline, orcreate_tube/update_tubenextTubeIds). An agent connected to just that tube (/api/mcp/tubes/{id}) may thencomplete_itemwithnextinto those tubes — and only those — although it cannot see them otherwise; its server instructions name them. The API key itself must be allowed to reach the target. The tube's currentnextTubeIdsare checked on every call, so changes apply to open connections (legacy SSE included) immediately. Folder-scoped and unscoped connections need no declaration.Long jobs (
leaseSeconds): set a tube's default lease above the job time (e.g. 1800 for video generation), or have agents claim withleaseSeconds/ callheartbeat_item; otherwise an expired lease lets another agent reclaim the item.Fan-out: several
nextentries (also into different tubes) — e.g. four image variants per prompt.Needs
items:pushin addition toitems:process(theagentrole has both); the next agent simply claims from the next tube.
UI components (shadcn/ui)
The dashboard uses shadcn/ui (style base-lyra,
Base UI primitives). Add components with npx shadcn@latest add <name>;
they land in components/ui and are imported as
import { Button } from "@/components/ui/button".
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Idempotency keys, locks, timers, and inboxes for agents over MCP. No payments.
Hosted MCP memory and agent control plane for durable conversations, jobs, and operations.
Sandboxes, storage, secrets, queues, timers, locks, inboxes and run ledger for AI bots. One MCP.
Persistent, inspectable memory for AI agents with lineage, correction, and a hosted MCP endpoint.
Related MCP Servers
- AlicenseCqualityCmaintenanceEnables durable, queryable multi-agent coordination with non-blocking peer messaging, task leases, and campaign-governed collaboration across sessions.59MIT
- AlicenseNot gradedqualityBmaintenanceExposes a self-hosted shared workspace over MCP where AI agents and their teammates read and write tasks, decisions, docs and results, so each session picks up where the last one left off. It adds hybrid cited search, per-workspace OAuth or scoped tokens, change feeds for cheap re-sync, and an append-only audit trail of every agent or human write.AGPL 3.0
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to store and retrieve persistent memory through MCP over HTTP (Streamable HTTP and compatible SSE) or stdio.2Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to claim, heartbeat, submit, split, park, and resume atomic work-queue tasks, with fencing tokens and receipts, while storing and versioning records and content-addressed files through MCP.1MIT