Connect an Agent

Set your API key once, and every client below uses the same URL and bearer header.

export VLMRUN_API_KEY="your-api-key"

{
  "mcpServers": {
    "vlmrun": {
      "type": "http",
      "url": "https://gateway.vlm.run/mcp",
      "headers": {
        "Authorization": "Bearer <VLMRUN_API_KEY>"
      }
    }
  }
}

Claude Desktop cannot use this shape. See the Claude Desktop tab.

from pydantic_ai import Agent
from pydantic_ai.capabilities import MCP

agent = Agent(
    "anthropic:claude-sonnet-5",
    capabilities=[
        MCP(
            "https://gateway.vlm.run/mcp",
            headers={"Authorization": "Bearer <VLMRUN_API_KEY>"},
        )
    ],
)

result = agent.run_sync(
    "Read https://storage.googleapis.com/vlm-data-public-prod/hub/examples/document.invoice/sample-invoice.pdf and tell me the total amount due."
)
print(result.output)

native=False is the default: Pydantic AI connects and calls the tools. native=True sends the URL to the model provider (OpenAI Responses, Anthropic, xAI), and the provider connects.

from langchain_mcp_adapters.client import MultiServerMCPClient
from langgraph.prebuilt import create_react_agent

client = MultiServerMCPClient(
    {
        "vlmrun": {
            "url": "https://gateway.vlm.run/mcp",
            "transport": "streamable_http",
            "headers": {"Authorization": "Bearer <VLMRUN_API_KEY>"},
        }
    }
)

tools = await client.get_tools()
agent = create_react_agent("anthropic:claude-sonnet-5", tools)

Install with pip install langchain-mcp-adapters langgraph.

import { MCPClient } from "@mastra/mcp";

const mcp = new MCPClient({
  servers: {
    vlmrun: {
      url: new URL("https://gateway.vlm.run/mcp"),
      requestInit: {
        headers: { Authorization: `Bearer ${process.env.VLMRUN_API_KEY}` },
      },
    },
  },
});

const tools = await mcp.getTools();

Pass tools to any Mastra Agent. Install with npm install @mastra/mcp.

from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp

async with MCPServerStreamableHttp(
    params={
        "url": "https://gateway.vlm.run/mcp",
        "headers": {"Authorization": "Bearer <VLMRUN_API_KEY>"},
    }
) as server:
    agent = Agent(
        name="Assistant",
        mcp_servers=[server],
    )
    result = await Runner.run(agent, "Summarize the attached PDF.")
    print(result.final_output)

claude mcp add --transport http vlmrun https://gateway.vlm.run/mcp \
  --header "Authorization: Bearer $VLMRUN_API_KEY"

Claude Desktop speaks MCP over stdio, and its connector UI cannot send Authorization. Bridge it with mcp-remote in claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "vlmrun": {
      "command": "/path/to/node/bin/npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://gateway.vlm.run/mcp",
        "--transport",
        "http-only",
        "--header",
        "Authorization:${VLM_AUTH}"
      ],
      "env": {
        "PATH": "/path/to/node/bin:/usr/local/bin:/usr/bin:/bin",
        "VLM_AUTH": "Bearer <VLMRUN_API_KEY>"
      }
    }
  }
}

Replace /path/to/node with the directory that holds Node.js. If npx is at /usr/local/bin/npx, use /usr/local. Claude Desktop does not inherit your shell PATH, so set command, PATH, and VLM_AUTH yourself. Node.js 18 or newer is required.

initialize returns server instructions that name each tool. Most clients inject them as the system message, so keep your own steering in the user turn. A second system message breaks strict OpenAI-compatible endpoints.

Call it without a framework

One POST calls a tool. The server issues no session id, so each request carries its own headers and any replica can answer. Send Accept: application/json, text/event-stream. The reply is a Server-Sent Events stream. The endpoint accepts POST only. GET /mcp returns 405.

MCP=https://gateway.vlm.run/mcp
HDRS=(-H "Authorization: Bearer $VLMRUN_API_KEY"
      -H "Content-Type: application/json"
      -H "Accept: application/json, text/event-stream")

curl -sN -X POST $MCP "${HDRS[@]}" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{
       "name":"list_models","arguments":{"modality":"document"}}}'

initialize returns the server instructions. It does not open a session.

curl -sN -X POST $MCP "${HDRS[@]}" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{
       "protocolVersion":"2025-06-18","capabilities":{},
       "clientInfo":{"name":"curl","version":"1"}}}'

Overview

Platform

OpenAI Compatibility

TypeSafe Compatibility

MCP

Misc

Connect an Agent

Call it without a framework

​Call it without a framework

Call it without a framework