@voightxyz/agents-mcp

Operate your Voight Agents from any MCP client.

List your deployed agents, check their state and usage, talk to them and wake their GPUs, from Claude Code, Cursor, Codex, VS Code, Claude Desktop or Gemini CLI.

Voight Agents · Docs · Voight

Voight Agents are autonomous AI agents you deploy in minutes. They run 24/7 on Voight cloud or on Nosana GPUs, browse the web, run scheduled tasks and work through the channels you connect (Telegram, GitHub and more). This package is a local Model Context Protocol server that lets your coding assistant operate them for you.

"Which of my agents are running, and how much did they use this week?"
"Ask my research agent for a summary of today's AI funding news."
"Wake my GPU agent and tell me when it is ready."

Quick start

1. Create an API key. Open voight.xyz/dashboard/settings, create a key and choose the access level Agents: operate. The key is shown once. Ingest keys (the ones used by @voightxyz/sdk) do not work here, by design.

2. Add the server to your client. It runs with npx, there is nothing to install.

claude mcp add --env VOIGHT_API_KEY=vk_your_key --transport stdio voight-agents -- npx -y @voightxyz/agents-mcp

To share the config with a team without sharing the secret, commit a .mcp.json that reads the key from each person's environment:

{
  "mcpServers": {
    "voight-agents": {
      "command": "npx",
      "args": ["-y", "@voightxyz/agents-mcp"],
      "env": { "VOIGHT_API_KEY": "${VOIGHT_API_KEY}" }
    }
  }
}

~/.cursor/mcp.json (or .cursor/mcp.json in a project):

{
  "mcpServers": {
    "voight-agents": {
      "command": "npx",
      "args": ["-y", "@voightxyz/agents-mcp"],
      "env": { "VOIGHT_API_KEY": "vk_your_key" }
    }
  }
}

.vscode/mcp.json. VS Code asks for the key once and stores it securely:

{
  "inputs": [
    { "type": "promptString", "id": "voight-api-key", "description": "Voight API key (Agents: operate)", "password": true }
  ],
  "servers": {
    "voight-agents": {
      "command": "npx",
      "args": ["-y", "@voightxyz/agents-mcp"],
      "env": { "VOIGHT_API_KEY": "${input:voight-api-key}" }
    }
  }
}

~/.codex/config.toml:

[mcp_servers.voight_agents]
command = "npx"
args = ["-y", "@voightxyz/agents-mcp"]
startup_timeout_sec = 30

[mcp_servers.voight_agents.env]
VOIGHT_API_KEY = "vk_your_key"

claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "voight-agents": {
      "command": "npx",
      "args": ["-y", "@voightxyz/agents-mcp"],
      "env": { "VOIGHT_API_KEY": "vk_your_key" }
    }
  }
}

~/.gemini/settings.json. Gemini CLI does not pass variables named like *KEY* from your shell, so the key has to be set in the env block:

{
  "mcpServers": {
    "voight-agents": {
      "command": "npx",
      "args": ["-y", "@voightxyz/agents-mcp"],
      "env": { "VOIGHT_API_KEY": "vk_your_key" }
    }
  }
}

3. Ask. "List my Voight agents" is a good first message.

Related MCP server: Agent5ive MCP Server

Tools

Run with --read-only (or VOIGHT_MCP_READ_ONLY=1) to expose only the first five tools.

How chat works

An agent can work on a single message for minutes: it searches, runs tools and writes files before it answers. MCP clients give a tool call much less time than that (60 seconds in several of them). So chat_with_agent waits up to about 50 seconds:

• If the reply is ready, you get it.

• If not, you get status: "running", a turn_ref and what the agent is doing right now. get_reply with that turn_ref collects the answer, and can be called as many times as needed.

A message is never sent twice: while a turn is running, a new message to the same agent is refused. The conversation continues across calls; pass new_conversation: true to start over.

Turns are kept in the memory of this process. If your client restarts the server while an agent is working, the turn_ref is lost. The agent still finishes on its side.

GPU agents

Agents hosted on Nosana GPUs stop their GPU when the paid hours end, and show up as gpu_stopped. wake_agent starts the GPU again, which takes a few minutes and can bill one GPU hour. Sending a chat message to a stopped agent also starts it, but that message is not delivered: wait until get_agent says ready, then send it.

Security and privacy

• Scoped key. The server only works with a key created with Agents: operate access (agents:read, agents:chat, agents:write). That key cannot deploy, delete or renew agents, cannot touch billing, and cannot create or list API keys. Revoke it at any time in Settings.

• The key goes to one place. Requests are only sent to https://api.voight.xyz. If VOIGHT_ENDPOINT points anywhere else (other than a localhost dev server) the server refuses to start, so a project config cannot redirect your key to another host.

• Agent output is fenced. Agents read the open web, inboxes and repos, so their replies can contain text written by a third party. Replies and task results are returned inside a block marked as untrusted content, with a random marker per call, and the model is told to treat it as data. This server never chains tool calls on its own.

• Bounded output. Results are capped at about 24,000 characters and say so when something was cut.

• What leaves your machine. The messages you send to an agent go to Voight, as they would from the dashboard. What comes back (agent names, personas, replies, task results, usage numbers) is handed to your MCP client and therefore to the model provider behind it. Account email and wallet are never returned.

• No telemetry. The package reads no files and sends nothing anywhere except the API calls above. Logs go to stderr.

• No transitive installs. The published bin is a single bundled file with zero runtime dependencies. Pin a version (@voightxyz/agents-mcp@0.1.0) if you want upgrades to be explicit.

Environment

Not in this version

Deploying, renewing and deleting agents, editing tasks and managing connectors are not exposed yet. Billing and API key management will stay in the dashboard.

Local development

npm install
npm run type-check
npm test
npm run build
npm run smoke                      # lists tools through the built binary
VOIGHT_API_KEY=vk_... npm run smoke  # also reads the account; never chats or wakes

src/
  cli.ts       entry point (stdio)
  config.ts    env and flags, endpoint allowlist
  api.ts       HTTP client and error messages
  chat.ts      chat turns with a bounded wait
  format.ts    compact views, size cap, untrusted fence
  server.ts    tool definitions

Inspect it with the MCP Inspector: npx @modelcontextprotocol/inspector node dist/cli.js.

License

Apache 2.0 © Voight. See LICENSE.