# VLM Run — how to use (mcp.ai)

Connect your VLM Run account and use 11 tools for document data extraction straight from your AI agent. Connect with your own API key. VLM Run provides multimodal agents, structured extraction, predictions, files, skills, feedback, and evaluation APIs.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_vlm_run?ms=1787296020000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `vlm_run_create_skill`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/vlm_run`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/vlm_run/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/vlm_run/create/skill` — Create a reusable skill from exactly one uploaded zip, prompt, or chat session.
  - body: { name?: string, prompt?: string, file_id?: string, is_public?: boolean, session_id?: string, description?: string, json_schema?: object }
- `POST https://api.mcp.ai/api/vlm_run/discover/extraction/schemas` — List supported structured-extraction domains, or return the full JSON schema for one domain when domain is provided.
  - body: { config?: object, domain?: string }
- `POST https://api.mcp.ai/api/vlm_run/execute/agent` — Start a VLM Run agent execution from an existing agent name or inline configuration over multimodal inputs. Execution may consume credits and is asynchronous by default; poll the returned ID with VLM_
  - body: { batch?: boolean, model?: string, config?: object, inputs?: object, metadata?: object, agent_name?: string, request_id?: string, callback_url?: string }
- `POST https://api.mcp.ai/api/vlm_run/extract/structured/json` — Start structured JSON extraction from images, a document, a video, or audio using a domain, custom schema, or skill. Extraction may consume credits; document, video, and audio runs are asynchronous by
  - body: { url?: string, batch?: boolean, model?: string, config?: object, domain?: string, images?: string[], file_id?: string, metadata?: object, modality: string, request_id?: string, callback_url?: string }
- `POST https://api.mcp.ai/api/vlm_run/find/files` — List uploaded files or find one by file ID or MD5 hash. In list mode, use offset and limit until has_more is false.
  - body: { limit?: integer, offset?: integer, file_id?: string, md5_hash?: string, generate_public_url?: boolean }
- `POST https://api.mcp.ai/api/vlm_run/find/skills` — List VLM Run skills or find one exact skill by ID, name, and optional version. In list mode, continue from next_offset while has_more is true.
  - body: { name?: string, limit?: integer, offset?: integer, grouped?: boolean, version?: string, order_by?: string, skill_id?: string, descending?: boolean }
- `POST https://api.mcp.ai/api/vlm_run/get/run` — Get the current status and result of one structured-extraction prediction or agent execution; call repeatedly to poll asynchronous work.
  - body: { run_id: string, run_type: string }
- `POST https://api.mcp.ai/api/vlm_run/list/agents` — Return agents available to the connected account for selection before execution.
- `POST https://api.mcp.ai/api/vlm_run/list/artifacts` — List artifact metadata belonging to exactly one chat session or agent execution. Use offset and limit to traverse pages until has_more is false.
  - body: { limit?: integer, offset?: integer, session_id?: string, execution_id?: string }
- `POST https://api.mcp.ai/api/vlm_run/list/runs` — List structured-extraction predictions or agent executions for the connected account. Use offset and limit to traverse pages until has_more is false.
  - body: { limit?: integer, offset?: integer, run_type: string }
- `POST https://api.mcp.ai/api/vlm_run/upload/file` — Upload a local file to VLM Run for extraction, agent input, or skill creation. Retain the returned file ID for tools that consume uploaded files.
  - body: { file: object, purpose?: string, generate_public_url?: boolean }

## Example prompts
- "What can I do in VLM Run?"
- "Show me a summary of my VLM Run account"

## More
- Page: https://mcp.ai/vlm_run
- Agent spec (llms.txt): https://mcp.ai/vlm_run/llms.txt
- Postman collection: https://mcp.ai/vlm_run/postman.json