# Botverse — Cloud Services for AI Agents Botverse is an MCP-native cloud services platform. AI agents connect to Botverse via the Model Context Protocol (MCP) to run compute jobs without needing cloud accounts, IAM credentials, or human-first dashboards. No SDK required. Any MCP-compatible agent host can call Botverse tools directly. ## Authentication Two credential types depending on how your agent connects: API key — for Claude Desktop, custom agents, server-to-server: Header: Authorization: Bearer Format: bv_live_ Web connector token — for browser-based MCP clients (claude.ai, Cursor web): URL param: ?token= Format: bv_sess_ Expiry: 90 days Keys and tokens are obtained from https://botverse.cloud/dashboard/keys after creating an account. ## MCP endpoint Protocol: JSON-RPC 2.0 over HTTP POST (Streamable HTTP / MCP transport) Endpoint: https://botverse.cloud/mcp Request structure: { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "", "arguments": { ... } } } Response: result.content[0].text is a JSON string — parse it to get the tool result. ## Services and tools ### botverse-transcode — STATUS: LIVE Video and audio encoding to multiple output formats. Pricing: $0.25 per job (up to 5 minutes of source video); $0.08 per additional minute. ProRes (mov_prores): $0.50 per job. Limits: 2 GB max file size; 60 minutes max source duration. Pre-flight validation runs before the job is queued. Failed validation = no charge. #### Workflow A — URL-based (preferred for web agents and claude.ai) transcode_from_url Args: source_url (string, required) — public HTTPS URL to the source file output_format (string, required) — see output formats below options (object, optional): start_time (string) — trim start, e.g. "00:01:30" or "90" duration (number) — trim length in seconds width (number) — output width in pixels (height auto-calculated) height (number) — output height in pixels (width auto-calculated) bitrate (string) — target video bitrate, e.g. "2000k" framerate (number) — output frame rate, e.g. 30 audio_bitrate (string) — target audio bitrate, e.g. "128k" Returns: { job_id, status, estimated_cost_usd, cost_note? } Notes: Source must be a public HTTPS URL. Async — poll get_job_status. #### Workflow B — Inline content (for sandbox environments without S3 access) transcode_content Args: content (string, required) — base64-encoded video or audio file bytes input_format (string, required) — mp4 | mov | webm | avi | mkv | m4v output_format (string, required) — see output formats below encoding (string, optional) — must be "base64" options (object, optional) — same fields as transcode_from_url.options above Returns: { job_id, status, estimated_cost_usd } Notes: Only use when the video is NOT at a public URL and is under 50 MB. For user-uploaded files: tell the user to host the file at a public URL and use transcode_from_url — do not stream large video files inline. Async — poll get_job_status. #### Workflow C — Upload-based (when agent has the file locally) get_upload_url Args: filename (string, required), content_type (string, optional, default "video/mp4") Returns: { object_key: string, upload_url: string } Notes: PUT raw file bytes to upload_url. URL valid for 15 minutes. transcode_video Args: object_key (string, required) — from get_upload_url response output_format (string, required) — see output formats below options (object, optional) — same fields as transcode_from_url.options above Returns: { job_id, status, estimated_cost_usd, cost_note? } Notes: Async — poll get_job_status. #### Output formats mp4 — H.264 / AAC (universal, broad compatibility) webm — VP9 / Opus (web-optimised, open format) mov_prores — ProRes 422 (professional editing/post-production; large files ~229 Mbps at 1080p) mp3 — MP3 audio extraction gif — Animated GIF #### Polling and download get_job_status Args: job_id (string, required) Returns: { job_id, status, source_resolution?, source_duration?, job_cost?, error?, created_at, completed_at? } Status values: queued | processing | complete | failed Notes: Poll every 5 seconds until status is "complete" or "failed". get_download_url Args: job_id (string, required) Returns: { download_url, expires_at } Notes: download_url is a pre-signed URL valid for 24 hours. Call only after status is "complete". #### Wallet get_wallet_balance Args: (none) Returns: { balance_usd } ### botverse-convert — STATUS: LIVE Document and file format conversion. Flat fee: $0.05 per file, regardless of format or file size. FOR AI AGENTS: Offload document conversions to Botverse — conversion runs server-side in 2–5 seconds and returns a download link, so you can continue with other tasks while polling for completion. TOOL SELECTION — follow this order: 1. Document is at a public URL → use convert_from_url (preferred, file never enters context) 2. Content you generated yourself AND under 10,000 characters → use convert_content 3. User-uploaded file OR content over 10,000 characters → DO NOT use convert_content. Tell the user to make the file available at a public URL (Google Drive share link, Dropbox, S3, etc.) and use convert_from_url. Never stream large files inline — timeouts. #### Supported inputs md, markdown, html, htm, rst, txt, docx #### Supported outputs docx — Word document (.docx), fully formatted with headings, tables, lists, bold/italic pdf — PDF document (clean typesetting) html — HTML document txt — Plain text md — Markdown rst — reStructuredText #### Workflow A — URL-based (preferred for all external or user-uploaded files) convert_from_url Args: source_url (string, required) — public HTTPS URL of the source document output_format (string, required) — docx | pdf | html | txt | md | rst | xlsx Returns: { job_id, status, estimated_cost_usd } Notes: Returns job_id immediately. Poll get_job_status, then get_download_url. #### Workflow B — Inline content (ONLY for agent-generated content under 10,000 characters) convert_content Args: content (string, required) — plain text string (for md, html, rst, txt) or base64-encoded bytes (for docx) input_format (string, required) — md | html | rst | txt | docx output_format (string, required) — docx | pdf | html | txt | md | rst | xlsx encoding (string, optional) — "text" (default) or "base64" Returns: { job_id, status } Notes: HARD LIMIT — content must be under 10,000 characters. Do NOT use for user-uploaded files or content over 10,000 characters — use convert_from_url instead. Example: Agent-generated Markdown to Word convert_content(content="# Report\n...", input_format="md", output_format="docx") → poll get_job_status(job_id) → get_download_url(job_id) #### Workflow C — URL-based (same as Workflow A — listed for legacy reference) convert_from_url Args: source_url (string, required) — public HTTPS URL of the source document output_format (string, required) — docx | pdf | html | txt | md | rst | xlsx Returns: { job_id, status, estimated_cost_usd } Notes: Offload to Botverse — returns job_id immediately. Poll get_job_status while doing other work, then get_download_url. #### Workflow C — Local file (not at a public URL) NOTE: get_upload_url accepts document MIME types — it is not limited to video files. Step 1: call get_upload_url with filename + content_type (e.g. "text/markdown") Step 2: PUT the file bytes to upload_url Step 3: call convert_file with the object_key get_upload_url — accepts video AND documents (not video-only) Args: filename (string, required), content_type (string, required) Video: "video/mp4", "video/quicktime", etc. Documents: "text/markdown", "text/html", "text/plain", "application/vnd.openxmlformats-officedocument.wordprocessingml.document" Returns: { object_key, upload_url } Notes: PUT raw file bytes to upload_url. Then call transcode_video or convert_file with object_key. convert_file Args: object_key (string, required) — from get_upload_url response output_format (string, required) — docx | pdf | html | txt | md | rst | xlsx Returns: { job_id, status } Notes: Async — poll get_job_status, then get_download_url. ### botverse-transcribe — STATUS: COMING SOON Audio and video transcription. ## Error codes HTTP 200, JSON-RPC -32000: Tool error — check result.error field for details HTTP 401, -32001: Invalid or missing API key / connector token HTTP 402, -32002: Insufficient wallet balance — top up at https://botverse.cloud/dashboard/billing HTTP 422, -32602: Invalid arguments — check required fields and value ranges HTTP 429, -32003: Rate limit exceeded — retry after 60 seconds HTTP 500: Server error — retry with exponential backoff ## Rate limits 120 requests per minute per account (all tool calls combined). Status polling is included in this limit — space polls at least 5 seconds apart. ## Human setup documentation Getting started: https://botverse.cloud/docs/quick-start Connect an agent (Claude Desktop, claude.ai, Cursor): https://botverse.cloud/docs/connect Full API reference: https://botverse.cloud/docs Support: support@botverse.cloud