/ Docs / MCP
MCP Reference

MCP Guide

MCP exposes ergonomic tools over Ultra endpoints while preserving protocol safety and one-time grant invariants.

Hosted MCP

Connect Streamable HTTP clients to /mcp. Discovery is published at /.well-known/mcp/server-card.json and /.well-known/mcp/manifest.json.

POST /mcp
Accept: application/json, text/event-stream
Content-Type: application/json
MCP-Protocol-Version: 2025-06-18
  • upload_text(content, filename?, ttl_seconds?, max_uses?, auth_mode?, allowed_agent_ids?, policy_metadata?)
  • upload_json(data?, json?, filename?, schema?, ttl_seconds?, max_uses?, auth_mode?, allowed_agent_ids?, policy_metadata?)
  • resolve_share(share)
  • request_grant(share)
  • download_link(share)

upload_json creates a normal Ultra file share with application/json and optional metadata.schema.

For file shares, resolve_share returns filename, mimeType, size, and expiresAt; mimeType is the canonical JSON content-type signal, while contentType is reserved for HTTP/R2 transport metadata.

Local Stdio Tools

Use mcp-server/server.py when a client needs local disk file access. The hosted endpoint cannot read files from a client machine.

  • upload_file(file_path, ttl_seconds?)
  • upload_text(content, filename?, ttl_seconds?)
  • download_file(file_id_or_url, save_path?)
  • download_share(share_url, save_path?, agent_key?)

Protected Flow Automation

For policy.mode=agent, MCP can orchestrate resolve → grant → fetch when an agent key or short-lived access token is available.

download_share(
  "https://ultra.egomonk.com/s/<shareId>",
  agent_key="agk_<keyId>.<secret>"
)
POST /api/agent/auth
GET  /api/share/{shareId}
POST /api/agent/grants
GET  /api/dl/{targetId} + X-Access-Grant

Cookbook

// Hosted /mcp
upload_text(content="hello", filename="hello.txt")
download_link(share="https://ultra.egomonk.com/s/shr_...")

// Local stdio server
upload_file(file_path="/tmp/artifact.zip", ttl_seconds=60)
download_share("https://ultra.egomonk.com/s/shr_...")

Operational Guidance

  • Store root agk_... credentials in secure server env only.
  • Use short TTLs for sensitive transfers.
  • Treat grant errors as one-time semantics and reissue when needed.
  • Hosted /mcp currently uses stateless POST request/response and returns 405 for standalone SSE GET.