> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.empiriolabs.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.empiriolabs.ai/_mcp/server. # MCP Server The EmpirioLabs MCP server lets any Model Context Protocol client run the whole platform as tools: chat with every text model, generate images, video, audio, speech, 3D and transcripts, run web search and research, manage jobs, batches, GPU Cloud, and hosted agents, and read your usage and balance. It is a remote server, so there is nothing to install. #### Server URL `https://mcp.empiriolabs.ai/mcp` (Streamable HTTP). Profiles such as `/mcp/inference` expose a subset of tools. #### Sign in or use a key Claude and ChatGPT sign you in with OAuth. Coding tools and scripts can send an EmpirioLabs API key as a bearer token instead. #### Always current Every model and feature EmpirioLabs adds is available here as it launches, at the same final prices and limits as the API. #### Your credits, your controls Connections use your credits. See and disconnect any connected app under **Settings** in the dashboard. ## Connect ### Claude (web, desktop, mobile) 1. Open **Settings**, then **Connectors**, and choose **Add custom connector**. 2. Enter `https://mcp.empiriolabs.ai/mcp` as the URL. Leave the OAuth client fields empty. 3. Click **Connect**, sign in to EmpirioLabs, review the request, and choose **Allow access**. Claude Code uses the same server: ```bash claude mcp add --transport http empiriolabs https://mcp.empiriolabs.ai/mcp ``` Run `/mcp` inside Claude Code to complete the sign-in the first time. ### ChatGPT 1. Open [EmpirioLabs AI](https://chatgpt.com/plugins/plugin_asdk_app_6abd51b0891c81918954286cdd388fa3) in the ChatGPT Plugins directory and install it. 2. Sign in to EmpirioLabs, review the request, and choose **Allow access**. 3. In a chat, type **@** and choose **EmpirioLabs AI**. You can also add the server yourself: open **Settings**, then **Plugins**, and turn on **Developer mode**. Then, on the **Plugins** page, choose **Add plugin**, then **Create app**, and enter `https://mcp.empiriolabs.ai/mcp` as the server URL with **OAuth** authentication. The server also provides the `search` and `fetch` tools ChatGPT uses for connectors, so it works in chat and in deep research. ### Cursor, VS Code, Windsurf, and other editors Remote servers are configured with a URL. Sign in through OAuth when the editor prompts, or add an API key header: ```json { "mcpServers": { "empiriolabs": { "url": "https://mcp.empiriolabs.ai/mcp", "headers": { "Authorization": "Bearer sk-empiriolabs-your_key_here" } } } } ``` VS Code reads the same shape from `.vscode/mcp.json` with a `servers` key and `"type": "http"`. Codex CLI: `codex mcp add empiriolabs --url https://mcp.empiriolabs.ai/mcp`. Gemini CLI and Windsurf accept the JSON block above in their MCP settings. ### Google Antigravity Antigravity uses a different key name than every other client on this page: the endpoint field is `serverUrl`, not `url`. Put this in `~/.gemini/config/mcp_config.json` for all projects, or in `plugins//mcp_config.json` to ship it with a plugin: ```json { "mcpServers": { "empiriolabs": { "serverUrl": "https://mcp.empiriolabs.ai/mcp", "headers": { "Authorization": "Bearer sk-empiriolabs-your_key_here" } } } } ``` Antigravity does not report a server that fails to connect: it is simply absent from the tool list, with no error. If the tools do not appear, check the key first. You can confirm what the agent sees by asking it to list its MCP servers and their tool counts. ### Grok, Perplexity, Le Chat and Gemini These assistants take the server as a custom connector; paste `https://mcp.empiriolabs.ai/mcp` and sign in when asked. * **Grok**: open `grok.com/connectors`, choose **New Connector**, then **Custom**, and enter the URL. * **Perplexity**: open **Settings**, then **Connectors**, choose **Custom connector**, then **Remote**, enter the URL with the **Streamable HTTP** transport and **OAuth 2.0**. * **Le Chat**: open **Connectors**, choose **Add Connector**, then the **Custom MCP Connector** tab, give it a name and enter the URL. * **Gemini**: open **Settings & help**, then **Connected Apps**, and add a custom app with the URL. ### Replit [Add EmpirioLabs AI to Replit](https://replit.com/integrations?mcp=eyJkaXNwbGF5TmFtZSI6IkVtcGlyaW9MYWJzIEFJIiwiYmFzZVVybCI6Imh0dHBzOi8vbWNwLmVtcGlyaW9sYWJzLmFpL21jcCJ9) opens Replit's MCP settings with the server filled in. Choose **Test & save** and sign in when asked. To use an API key instead, open **Advanced settings** and add an `Authorization` header with the value `Bearer sk-empiriolabs-your_key_here`. Replit Agent can then use the tools in all your projects. ### Hermes Agent and OpenClaw Setup for both agents is on the integrations page: [MCP server in Hermes](/integrations#mcp-server-in-hermes) signs in with OAuth or uses an API key, and [MCP server in OpenClaw](/integrations#mcp-server-in-openclaw) uses an API key. ### Vercel AI SDK The AI SDK MCP client connects with an API key and turns the server's tools into AI SDK tools: ```bash npm install ai @ai-sdk/mcp ``` **`mcp-tools.ts`** ```ts title="mcp-tools.ts" import { createMCPClient } from '@ai-sdk/mcp'; const mcpClient = await createMCPClient({ transport: { type: 'http', url: 'https://mcp.empiriolabs.ai/mcp', headers: { Authorization: `Bearer ${process.env.EMPIRIOLABS_API_KEY}` }, }, }); const tools = await mcpClient.tools(); // Pass `tools` to generateText or streamText, then: await mcpClient.close(); ``` To call EmpirioLabs models from the same app, see [Vercel AI SDK](/integrations#vercel-ai-sdk) on the integrations page. ### Any HTTP client The server speaks JSON-RPC over `POST https://mcp.empiriolabs.ai/mcp` and answers with JSON. Send `Authorization: Bearer ` and `Accept: application/json, text/event-stream` on every request. ```bash curl "https://mcp.empiriolabs.ai/mcp" \ -H "Authorization: Bearer $EMPIRIOLABS_API_KEY" \ -H "Accept: application/json, text/event-stream" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_models","arguments":{"modality":"image","limit":5}}}' ``` ## How access works * **OAuth sign-in.** Claude, ChatGPT, and other OAuth clients open an EmpirioLabs sign-in. You approve the request on the dashboard and the app is connected; it receives short-lived tokens and refreshes them on its own. Clients that need it can discover sign-in through the standard resource metadata at `https://mcp.empiriolabs.ai/.well-known/oauth-protected-resource`. An app that calls the API itself, rather than the MCP server, connects the same way: see [Sign in with EmpirioLabs AI](/oauth). * **API key.** Send any active EmpirioLabs API key as the bearer token to get every tool without a sign-in step. This suits editors, scripts, and servers you control. * **Disconnecting.** Open [Settings](https://platform.empiriolabs.ai/dashboard/profile) in the dashboard and disconnect the app under **Connected applications**; it loses access immediately and asks you to sign in again the next time you use it. Apps can also disconnect themselves through the standard revocation endpoint. * **Scopes.** Each toolset below is also an OAuth scope, so an app can ask for only what it needs and the consent screen shows exactly what you are granting. ## Profiles Every toolset is available at `https://mcp.empiriolabs.ai/mcp`. Add a profile or a `+` separated list of toolsets to the path to expose a smaller, focused tool list, for example when a client works best with fewer tools or when you want a connection that cannot generate media. ## Jobs and long-running generation Image, video, audio, transcription, 3D, Compose, and agent tools return finished output URLs when the work completes within the wait window (default 40 seconds, at most 50). Otherwise they return a `job_id` and the client should call `get_job`, which can also wait, instead of starting the generation again. Output URLs are signed and expire, so download anything you want to keep. Chat, search, and research tools answer inline. ## Example prompts * "List the cheapest video models on EmpirioLabs, then generate a 5 second clip of waves at sunset with the best value one." * "Use EmpirioLabs to transcribe this recording, then summarize the action items with qwen3-7-max." * "Check my EmpirioLabs balance and show what I spent on image generation this week." * "Deploy an H100 on EmpirioLabs GPU Cloud with the vLLM template and tell me when it is ready." * "Run a web research task about the latest MCP specification changes and cite sources." ## Where it is listed EmpirioLabs AI is available as an app in the [ChatGPT Plugins directory](https://chatgpt.com/plugins/plugin_asdk_app_6abd51b0891c81918954286cdd388fa3), in the [GitHub MCP Registry](https://github.com/mcp/ai.empiriolabs/mcp) for VS Code and GitHub Copilot, as a [certified Microsoft connector](https://learn.microsoft.com/en-us/connectors/empiriolabsai/) for Copilot Studio, Power Automate, Power Apps and Logic Apps, and in the [LobeHub MCP marketplace](https://lobehub.com/mcp/empiriolabs-ai-mcp) for LobeChat, so you can add it from any of them instead of typing the URL. ## Prices, limits, and errors Tools use the same final prices as [Models and Pricing](/models-pricing), the same account limits as [Limits and API Keys](/rate-limits-api-keys), and the same error messages as [Errors and Status Codes](/errors). A tool result with `isError` carries the same actionable message the API returns, for example when a model does not support the requested endpoint or when the account needs credits. ## Privacy Prompts and outputs are not stored for inspection. Usage records keep only metadata such as model, tokens, cost, and status. See the [Privacy Policy](https://empiriolabs.ai/privacy-policy) and [Support](/support). ## Tool reference Tools are grouped by toolset. A toolset is also the scope an app asks for when it connects, so the consent screen and this reference use the same names. ### Toolsets and scopes | Toolset (OAuth scope) | What it allows | Tools | | --------------------- | -------------------------------------------------------------------------------------------------- | ----- | | `models` | Browse the model catalog, prices, capabilities, and parameters | 5 | | `text` | Run chat, embeddings, reranking, decisions, and AI text detection (uses credits) | 5 | | `search` | Run web search, grounded answers, and research (uses credits) | 3 | | `media` | Generate and edit images, video, audio, speech, transcription, document OCR, and 3D (uses credits) | 14 | | `jobs` | Check, wait for, and cancel generation jobs | 3 | | `agents` | Run and manage agent tasks (uses credits) | 4 | | `account` | Read usage history and the current balance | 1 | | `batch` | Upload batch files and manage batch jobs (uses credits) | 6 | | `gpu` | Deploy and manage GPU instances, clusters, and volumes (billable) | 20 | | `hosted_agents` | Create and manage hosted agents (billable) | 22 | ### Profiles | URL | Toolsets | | ------------------------------------------ | --------------------------------------------- | | `https://mcp.empiriolabs.ai/mcp` | all toolsets | | `https://mcp.empiriolabs.ai/mcp/inference` | `models`, `text`, `search`, `jobs`, `account` | | `https://mcp.empiriolabs.ai/mcp/media` | `models`, `media`, `jobs`, `account` | | `https://mcp.empiriolabs.ai/mcp/cloud` | `models`, `account`, `gpu`, `hosted_agents` | Combine toolsets or profiles with `+`, for example `https://mcp.empiriolabs.ai/mcp/models+text+jobs`. ### `models` tools | Tool | Description | Access | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | | `list_models` | List EmpirioLabs models with author, modality, endpoints and final prices. Filter by free-text query, modality (text, image, video, audio, multimodal, 3D), category, author, or endpoint path. | read-only | | `get_model` | Get one model's full schema: description, endpoints, context window, final prices, notes, and every supported parameter with defaults and ranges. | read-only | | `search` | Search the EmpirioLabs model catalog and documentation. Returns result ids: model:\ for a model, doc:\ for a documentation page. | read-only | | `fetch` | Fetch the full text of a search result by id (model:\ or doc:\). | read-only | | `get_platform_status` | Check whether the EmpirioLabs API and its models are currently up, with per-model availability. | read-only | ### `text` tools | Tool | Description | Access | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | | `chat` | Run a chat completion on any EmpirioLabs chat model and return the assistant reply, reasoning (when the model exposes it), tool calls and token usage. Uses credits. | read-only | | `embeddings` | Create embedding vectors for one or more texts with an embedding model. Uses credits. | read-only | | `rerank` | Score and reorder documents by relevance to a query with a reranking model. Uses credits. | read-only | | `decide` | Answer typed questions about a state with a decision model and return calibrated probabilities instead of generated text. Put text, JSON, images, audio or video in state, then ask yes/no (noul), multiple-choice (choice), ordered-scale (score) or which-function (tool) questions. Each answer includes its probabilities and a confidence value. Uses credits. | read-only | | `detect_ai_text` | Classify whether text was written by an AI model (GPTZero). Uses credits. | read-only | ### `search` tools | Tool | Description | Access | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | | `web_search` | Run a live web search through a search model (for example exa-search, tavily-search, linkup-search). Returns results with titles, URLs and snippets. Uses credits. | read-only | | `web_research` | Run a multi-step research task with citations (for example tavily-research, exa-research, linkup-deep-search). Takes up to a few minutes. Uses credits. | read-only | | `web_answer` | Get a one-shot answer with citations from a grounded answer model (for example exa-answer). Uses credits. | read-only | ### `media` tools | Tool | Description | Access | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | | `generate_image` | Generate images from a prompt with an image model. Returns signed output URLs, or a job_id when generation takes longer than the wait. Uses credits. | write | | `generate_video` | Generate a video from a prompt or an image with a video model. Video takes minutes, so the tool returns a job_id for the running job. Uses credits. | write | | `list_generation_templates` | List curated image and video generation templates (creative effects) with their slug, modality, recommended model and inputs. | read-only | | `get_generation_template` | Get one generation template by slug, including its prompt guidance, recommended model and default parameters. | read-only | | `list_compose_recipes` | List the Compose recipes that chain script, visuals, voice and music into a finished video, with their modes and inputs. | read-only | | `compose_video` | Create a finished video from a Compose recipe (brief, script, storyboard or edits). Returns a job_id for the running job. Uses credits. | write | | `generate_3d` | Generate a 3D model from an image with a 3D generation model (for example trellis-2-4b). Returns a job_id for the running job. Uses credits. | write | | `text_to_speech` | Synthesize speech from text with a TTS model and voice. Returns a signed audio URL (or inline audio). Uses credits. | write | | `list_voices` | List the voices available for text-to-speech, filterable by model, language, gender or search text. | read-only | | `generate_audio` | Generate music or sound effects from a prompt with an audio generation model (for example ace-step-1-5-xl). Returns a signed URL or a job_id for the running job. Uses credits. | write | | `transcribe_audio` | Transcribe an audio or video file at an https URL with a speech-to-text model. Returns the transcript or a job_id for the running job. Uses credits. | write | | `read_document` | Read a PDF or an image at a public URL (or a base64 data URI) with a document OCR model and return every page as Markdown, with image regions, tables, headers and footers. Choose pages with zero-based numbers. Returns the pages, or a job_id for a long document. Uses credits. | read-only | | `analyze_image` | Ask a question about an image with a vision-capable model and get a text answer. Uses credits. | read-only | | `edit_image` | Edit an existing image with an instruction using an image-edit model. Returns signed output URLs or a job_id for the running job. Uses credits. | write | ### `jobs` tools | Tool | Description | Access | | ------------ | --------------------------------------------------------------------------------------------------------------------------- | ----------- | | `list_jobs` | List the account's recent asynchronous jobs, newest first. | read-only | | `get_job` | Get the status and result of an asynchronous generation job by job_id. Optionally wait up to wait_seconds for it to finish. | read-only | | `cancel_job` | Cancel a queued or processing job. Completed jobs are returned unchanged. | destructive | ### `agents` tools | Tool | Description | Access | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | `run_agent_task` | Start a long-running agent task (for example with the manus model) or send a follow-up message to an existing task. Returns the job_id and the task_id of the agent task. Uses credits. | write | | `get_agent_task` | Get the status and output of an agent task. | read-only | | `get_agent_task_messages` | List the messages exchanged during an agent task. | read-only | | `stop_agent_task` | Stop a running agent task. | destructive | ### `account` tools | Tool | Description | Access | | ------------------- | ----------------------------------------------------------------------------------------------------------- | --------- | | `get_account_usage` | Read the account's current credit balance and recent usage history (model, endpoint, tokens, cost, status). | read-only | ### `batch` tools | Tool | Description | Access | | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | `upload_batch_file` | Upload a JSONL file of requests for the Batch API (one \{custom_id, method, url, body} object per line). Returns the id of the uploaded file. | write | | `get_batch_file_content` | Download the content of a batch input, output, or error file as JSONL text. | read-only | | `create_batch` | Start a batch run from an uploaded JSONL file. Each line bills at the batch price when it executes. Uses credits. | write | | `list_batches` | List the account's batch runs. | read-only | | `get_batch` | Get a batch run's status, counts and output file ids. | read-only | | `cancel_batch` | Cancel a batch run; lines that already executed stay billed. | destructive | ### `gpu` tools | Tool | Description | Access | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | `list_gpu_types` | List the GPU types available to rent with hourly prices, VRAM, and availability. | read-only | | `get_gpu_type` | Get one GPU type by slug. | read-only | | `order_gpu_cluster` | Order a multi-node GPU cluster from a fabric. Creates billable infrastructure charged by the hour. | destructive | | `list_gpu_clusters` | List multi-node GPU clusters for distributed training, with node counts, prices and ordering availability. | read-only | | `list_gpu_volumes` | List the account's persistent GPU volumes. | read-only | | `create_gpu_volume` | Create a persistent volume that can be attached to GPU instances. Billable storage. | destructive | | `get_gpu_volume` | Get one GPU volume. | read-only | | `delete_gpu_volume` | Delete a GPU volume and everything stored on it. | destructive | | `list_gpu_instances` | List the account's GPU instances with status, GPU type, hourly price and connection details. | read-only | | `deploy_gpu_instance` | Rent a GPU and start a workload on it (a template, a Hugging Face model, or a container image). Creates a billable instance charged by the hour until you destroy it. | destructive | | `get_gpu_instance` | Get one GPU instance's status, endpoints and cost so far. | read-only | | `destroy_gpu_instance` | Destroy a GPU instance and stop its hourly charges. Data on the instance disk is lost unless it is on an attached volume. | destructive | | `list_gpu_ssh_keys` | List the SSH public keys on the account. Any of them can connect to the account's running GPU instances. | read-only | | `create_gpu_ssh_key` | Add an SSH public key to the account so it can connect to any running GPU instance with the instance's ssh.command. Send the public key, or generate: true to have a key pair created and returned once (use that private key with -i for both hosts: ssh -i \ -o ProxyCommand="ssh -i \ -p \ -W %h:%p ssh.empiriolabs.ai" root\@gpu-\). Never send a private key. | write | | `delete_gpu_ssh_key` | Delete an SSH key from the account. It can no longer open new connections to the account's GPU instances. | destructive | | `add_gpu_ssh_key` | Add an SSH public key to the account, prepare SSH on one running GPU instance with it, and return the ssh command to connect. Use this before a first connection to skip the setup wait. | write | | `run_gpu_command` | Run one shell command as root inside a running GPU instance's workload container and return its exit code, stdout and stderr. Use it to install packages, check the GPU with nvidia-smi, run a script, or read logs. Each call starts a fresh shell. | destructive | | `gpu_instance_action` | Stop (pauses hourly compute charges), start, or refresh a GPU instance. | destructive | | `gpu_workload_send` | Send a POST, PUT, PATCH, or DELETE request with a JSON body to the workload running on your GPU instance through the authenticated connect endpoint ([https://docs.empiriolabs.ai/gpu-cloud](https://docs.empiriolabs.ai/gpu-cloud)). For example call an LLM server you deployed. | destructive | | `gpu_workload_get` | Send a GET request to the workload running on your GPU instance through the authenticated connect endpoint ([https://docs.empiriolabs.ai/gpu-cloud](https://docs.empiriolabs.ai/gpu-cloud)). Useful for health checks and reading results. | read-only | ### `hosted_agents` tools | Tool | Description | Access | | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ----------- | | `get_hosted_agents_health` | Check whether the hosted-agents service is available. | read-only | | `get_hosted_agent_plans` | Get the hosted-agent plans, runtime presets and defaults available to the account. | read-only | | `list_hosted_agents` | List the account's hosted agents with status, runtime type, plan and model. | read-only | | `create_hosted_agent` | Create a private hosted agent (OpenClaw or Hermes runtime) on a plan. Creates a billable resource. | destructive | | `get_hosted_agent` | Get one hosted agent's status, configuration and connection details. | read-only | | `delete_hosted_agent` | Destroy a hosted agent, its storage and its channels, and stop its charges. | destructive | | `rename_hosted_agent` | Change a hosted agent's display name. | destructive | | `hosted_agent_action` | Start, stop, restart, or refresh a hosted agent's runtime. | destructive | | `message_hosted_agent` | Send chat messages to a running hosted agent and return its reply. The agent may use its connected tools. Uses credits. | destructive | | `list_hosted_agent_integrations` | List the messaging channels and integrations connected to a hosted agent. | read-only | | `save_hosted_agent_integration` | Connect or update a messaging channel or integration (for example telegram, discord, slack) on a hosted agent. | destructive | | `disconnect_hosted_agent_integration` | Disconnect a messaging channel or integration from a hosted agent. | destructive | | `set_hosted_agent_channel_behavior` | Set how a hosted agent behaves on one messaging channel (for example reply rules). | destructive | | `set_hosted_agent_model` | Switch the model or provider a hosted agent uses. | destructive | | `set_hosted_agent_access` | Set the access mode and allow list for who can message a hosted agent on its channels. | destructive | | `list_hosted_agent_skills` | List the skills installed on a hosted agent. | read-only | | `add_hosted_agent_skill` | Install a catalog skill (by slug) or a custom skill on a hosted agent. | write | | `remove_hosted_agent_skill` | Uninstall a skill from a hosted agent. | destructive | | `list_hosted_agent_mcp_connectors` | List the remote MCP connectors attached to a hosted agent. | read-only | | `add_hosted_agent_mcp_connector` | Attach a remote MCP server to a hosted agent so the agent can use its tools. | write | | `remove_hosted_agent_mcp_connector` | Detach a remote MCP connector from a hosted agent. | destructive | | `get_hosted_agent_stats` | Get activity counts for a hosted agent. | read-only | ### Prompts Prompts are ready-made requests that chain several tools. Clients that support MCP prompts list them next to the tools; a connection sees the prompts whose toolsets it was granted. | Prompt | What it does | Arguments | Toolsets | | ------------------------- | ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | ------------------------- | | `choose_model` | Compare EmpirioLabs models for a task and recommend one, with a cheaper fallback and final prices. | `task`, `modality` (optional), `priority` (optional) | `models` | | `research_with_citations` | Answer a question from live web research and cite every source. | `question`, `depth` (optional) | `search` | | `generate_media` | Create an image, video, audio track or 3D asset from a description and return the finished files. | `description`, `kind` (optional), `model` (optional) | `models`, `media`, `jobs` | | `deploy_gpu_workload` | Rent a GPU on EmpirioLabs GPU Cloud, start a workload on it and report the endpoints and hourly cost. | `workload`, `gpu` (optional), `max_hourly_price` (optional) | `gpu` | | `spend_report` | Summarise the account balance, recent usage and everything that is still running and billing. | `period` (optional) | `account`, `jobs` |