# Staging

Staging gives agents a short-lived **public https URL** for large binaries and text documents so other MCP tools (Whisper, PDF/DOCX, img, …) can fetch them. Max size 1 GiB; objects expire after ~24 hours and are deleted. Preferred for large binaries: HTTP multipart `POST /staging/upload` with `Authorization: Bearer mcp_…`. Preferred for markdown/HTML from an agent: `staging_put_text` (plain UTF-8 — no base64). `staging_put_base64` is only for small binary test clips.

**Service id:** `staging`  
**Version:** `0.2.0`  
**Status:** `available`

## Authentication

MCP endpoint: `https://mcp.glc-rag.hu/mcp` (streamable HTTP)

**Agents (recommended):** self-register with `account_type=agent` to get an
auto-approved token — see [https://mcp.glc-rag.hu/guide/agent](https://mcp.glc-rag.hu/guide/agent).

Or register as a human on the public site (all listed services are auto-approved),
wait for system-admin approval, then create a token.

```http
Authorization: Bearer mcp_...
```

Cursor `mcp.json` example:

```json
{
  "mcpServers": {
    "staging": {
      "url": "https://mcp.glc-rag.hu/mcp",
      "headers": {
        "Authorization": "Bearer mcp_YOUR_TOKEN"
      }
    }
  }
}
```

## Tools

### `staging_ingest_url`

Download a public http(s) URL into staging and return a temporary public https URL on this platform (max 1 GiB). Use when the file is already online and you need a stable short-lived URL for whisper_job_start or other tools. Returns immediately after the download finishes (may take time for large files).

**Input schema:**

```json
{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "Public http(s) source URL to copy into staging"
    },
    "filename": {
      "type": "string",
      "description": "Optional filename hint"
    }
  },
  "required": [
    "url"
  ],
  "additionalProperties": false
}
```

**Examples:**

```json
{
  "url": "https://example.com/meeting.mp3",
  "filename": "meeting.mp3"
}
```

### `staging_put_text`

Store UTF-8 text (markdown, HTML, plain text, JSON, …) in staging and return a public URL. Prefer this over base64 for documents — models handle plain text tool args reliably. Then pass url to markdown_to_pdf / markdown_to_docx / html_to_*. Size-limited (default 2 MiB). For large binaries use POST /staging/upload.

**Input schema:**

```json
{
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "description": "UTF-8 document body (markdown/HTML/plain text)"
    },
    "filename": {
      "type": "string",
      "description": "Optional filename hint (e.g. report.md, page.html)"
    },
    "content_type": {
      "type": "string",
      "description": "Optional MIME type; default guessed from filename (text/markdown, text/html, text/plain, \u2026)"
    }
  },
  "required": [
    "text"
  ],
  "additionalProperties": false
}
```

**Examples:**

```json
{
  "text": "# Report\n\nHello **world**.\n",
  "filename": "report.md"
}
```

```json
{
  "text": "<h1>Invoice</h1><p>42 EUR</p>",
  "filename": "invoice.html",
  "content_type": "text/html; charset=utf-8"
}
```

### `staging_put_base64`

Store small/medium base64 content in staging and return a public URL. Hard limit 1 GiB but base64 through MCP is impractical above tens of MB — for documents prefer staging_put_text; for large audio use HTTP POST /staging/upload.

**Input schema:**

```json
{
  "type": "object",
  "properties": {
    "content_base64": {
      "type": "string"
    },
    "filename": {
      "type": "string"
    },
    "content_type": {
      "type": "string",
      "default": "application/octet-stream"
    }
  },
  "required": [
    "content_base64"
  ],
  "additionalProperties": false
}
```

**Examples:**

```json
{
  "content_base64": "<base64>",
  "filename": "clip.wav"
}
```

### `staging_info`

Return metadata for a staging object_id if it still exists and has not expired.

**Input schema:**

```json
{
  "type": "object",
  "properties": {
    "object_id": {
      "type": "string"
    }
  },
  "required": [
    "object_id"
  ],
  "additionalProperties": false
}
```

**Examples:**

```json
{
  "object_id": "0123456789abcdef0123456789abcdef"
}
```

### `staging_delete`

Delete a staging object early (before TTL).

**Input schema:**

```json
{
  "type": "object",
  "properties": {
    "object_id": {
      "type": "string"
    }
  },
  "required": [
    "object_id"
  ],
  "additionalProperties": false
}
```

**Examples:**

```json
{
  "object_id": "0123456789abcdef0123456789abcdef"
}
```

## Usage notes

Text / markdown / HTML (agent-friendly, no base64):
1. `staging_put_text({ text, filename? })` → `{url}`
2. Pass `url` to `markdown_to_pdf` / `markdown_to_docx` / `html_to_*` etc.

Large binary (recommended):
1. `POST https://mcp.glc-rag.hu/staging/upload` with Bearer MCP token + multipart file
2. Response `{object_id, url, expires_at, bytes}`
3. Pass `url` to `whisper_job_start` (or other tools)

Already-public remote file: call `staging_ingest_url` then use returned `url`.
Poll/info: `staging_info`. Cleanup early: `staging_delete`.
Objects auto-expire; do not treat staging as permanent storage.

## Errors / limits

Oversized (>1 GiB binary / text limit), empty, SSRF-blocked URL, expired/missing id, storage full → error. Upload without valid MCP token → 401. Service not approved → no tools / 403.

## Agent discovery

- Agent registration: `https://mcp.glc-rag.hu/guide/agent`
- Markdown: `https://mcp.glc-rag.hu/guide/staging.md`
- Index: `https://mcp.glc-rag.hu/llms.txt`
- MCP resource: `docs://staging`