Skip to main content
Connect your AI agent to VLM Run’s remote MCP server and start building agentic workflows with visual AI in minutes.

​
Installation

Get your API key

Head over to the VLM Run Dashboard to get your API key ($VLMRUN_API_KEY). We’ll use this to authenticate your requests to the MCP server next.

Ping the MCP server to test

The MCP server is available at the following endpoint:
https://mcp.vlm.run/mcp/sse
Authentication is handled via Bearer token in the Authorization header. The server URL no longer includes the API key directly.

Add the server to your MCP client

  • Claude Desktop
  • Claude Pro (Web)
  • OpenAI Responses API SDK
  • Cursor
Add this configuration to your Claude Desktop MCP settings:
  • Location (Mac) ~/Library/Application Support/Claude/claude_desktop_config.json
  • Location (Windows) %APPDATA%/Claude/claude_desktop_config.json See docs for more details.
{
  "mcpServers": {
    "vlm-run-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.vlm.run/mcp/sse",
        "--transport",
        "sse-only",
        "--header",
        "Authorization:Bearer ${VLMRUN_API_KEY}"
      ],
      "env": {
        "VLMRUN_API_KEY": "<your-vlmrun-api-key>"
      }
    }
  }
}
Restart Claude Desktop after adding the configuration.

Test the connection

Ask your AI agent to list available tools
List available VLM Run tools
Expected response: A list of available tools like put_image_url, put_document_url, detect_faces, etc.

​
Try your VLM Run MCP tool interaction

Let’s extract details from an invoice image using VLM Run MCP tools:
  • Claude Desktop
  • OpenAI Responses API SDK
  • Claude Pro (Web)
  • Cursor
Extract invoice data from this image (https://storage.googleapis.com/vlm-data-public-prod/hub/examples/document.invoice/invoice_1.jpg) using the document.invoice domain
Claude will automatically use the VLM Run MCP server to process your image and return structured JSON data.

​
Troubleshooting

  • Verify the configuration file path and JSON syntax
  • Restart Claude Desktop completely
  • Check that npx is installed and accessible
  • Ensure the server URL is exactly https://mcp.vlm.run/mcp/sse with Bearer token authentication
  • Verify you’re using OpenAI Python SDK version 1.74.0 or higher
  • Check that the server URL and label are correct in your tools configuration
  • Ensure your OpenAI API key has the necessary permissions
  • Ensure you have a Claude Pro, Max, Team, or Enterprise plan (custom integrations not available on free tier)
  • Verify the server URL is exactly https://mcp.vlm.run/mcp/sse with proper Bearer token authentication when adding the integration
  • Check that the integration appears in Settings > Integrations after adding
  • Use the “Search and tools” menu in chat to enable specific VLM Run tools
  • Try refreshing the page if tools don’t appear immediately after configuration
  • Verify the ~/.cursor/mcp.json file exists in your project root
  • Check JSON syntax and ensure the server URL is exactly https://mcp.vlm.run/mcp/sse with Bearer token authentication
  • Restart Cursor completely after configuration changes
  • Ensure npx is installed and accessible from your system PATH
  • Verify internet connectivity
  • Check if https://mcp.vlm.run/mcp/sse is accessible (note: authentication is required via Bearer token)
  • Try restarting your MCP client
  • Check for firewall or proxy issues blocking HTTPS connections
  • Ensure the MCP server connected successfully
  • Try calling list_hub_domains first to verify connection
  • Check tool name spelling (e.g., extract_image not extract-image)
  • Verify the domain name exists (e.g., document.invoice not invoice)
Need help? Join our Discord channel or contact our support team to get help.
⌘I