Connect Cursor, Windsurf, and Claude Code to VoidLLM

VoidLLM works with any tool that supports the OpenAI-compatible API or MCP. Here’s how to connect the most popular AI coding assistants.

VoidLLM as LLM proxy

VoidLLM exposes an OpenAI-compatible /v1 endpoint. Any tool that lets you set a custom OpenAI base URL works out of the box.

Cursor

In Cursor Settings > Models > OpenAI API Base:

https://your-voidllm/v1

Set your API key to your VoidLLM key (vl_uk_...). Select the model alias you configured in VoidLLM (e.g. default).

Windsurf

In Windsurf settings, add a custom provider with your VoidLLM endpoint:

Base URL: https://your-voidllm/v1
API Key: vl_uk_your_key_here

VoidLLM as MCP server

This is where it gets interesting. VoidLLM exposes built-in management tools and proxies external MCP servers through a single endpoint. Your AI assistant can check model health, look up usage, create API keys, and call tools on any registered MCP server - all through VoidLLM.

Claude Code

Add to your Claude Code MCP config (~/.claude/mcp.json or project .mcp.json):

{
  "mcpServers": {
    "voidllm": {
      "url": "https://your-voidllm/api/v1/mcp/voidllm",
      "headers": {
        "Authorization": "Bearer vl_uk_your_key_here"
      }
    }
  }
}

This gives Claude Code access to 6 built-in tools: list_models, get_model_health, get_usage, list_keys, create_key, and list_deployments.

With Code Mode

For Code Mode (multi-tool orchestration in a single execution), point to the Code Mode endpoint instead:

{
  "mcpServers": {
    "voidllm-code": {
      "url": "https://your-voidllm/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer vl_uk_your_key_here"
      }
    }
  }
}

This adds list_servers, search_tools, and execute_code - your AI agent can discover and orchestrate tools across all your registered MCP servers.

External MCP servers through VoidLLM

If you have external MCP servers registered (like AWS Knowledge or Exa Search), each one gets its own endpoint:

{
  "mcpServers": {
    "aws": {
      "url": "https://your-voidllm/api/v1/mcp/aws",
      "headers": {
        "Authorization": "Bearer vl_uk_your_key_here"
      }
    }
  }
}

The advantage over connecting directly: VoidLLM handles auth to the upstream server, enforces access control, and logs every tool call. Your IDE only needs one credential - your VoidLLM API key.

Troubleshooting

401 Unauthorized - your API key is wrong or expired. Check with curl -H "Authorization: Bearer vl_uk_..." https://your-voidllm/api/v1/orgs.

Model not found - the model name or alias you’re using in the IDE doesn’t exist in VoidLLM. Check available models in the UI or via list_models.

MCP server access denied - global MCP servers are closed-by-default. An org admin needs to grant access in Organization > MCP Servers.

Connection refused - VoidLLM isn’t reachable from your IDE. Check firewall rules, ports, and that VoidLLM is actually running.