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:
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
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.
Restart Claude Desktop after adding the configuration.
Test the connection
Ask your AI agent to list available toolsExpected 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:Troubleshooting
Claude Desktop not showing MCP tools
Claude Desktop not showing MCP tools
- 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
OpenAI Responses API SDK not recognizing MCP server
OpenAI Responses API SDK not recognizing MCP server
- 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
Claude Pro (Web) integration issues
Claude Pro (Web) integration issues
- 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
Cursor not showing MCP tools
Cursor not showing MCP tools
- 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
Connection timeout or server unreachable
Connection timeout or server unreachable
- 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
Tool not found or extraction errors
Tool not found or extraction errors
- Ensure the MCP server connected successfully
- Try calling
list_hub_domains
first to verify connection - Check tool name spelling (e.g.,
extract_image
notextract-image
) - Verify the domain name exists (e.g.,
document.invoice
notinvoice
)
Need help? Join our Discord channel or contact our support team to get help.